Skip to content

Commit 57fb801

Browse files
os-justinclaude
andauthored
docs(cli): os create plugin's standalone output is unscoped and private (#17547)
The #15530 ruling landed in PR #17096: the standalone default emission of `os create plugin` names the package `plugin-<name>` — unscoped — and writes `"private": true`. `--in-repo` is unchanged and still emits a publishable `@objectstack/plugin-<name>` under `packages/plugins/`. Three hand-written statements still promised the pre-ruling behaviour and sent a reader to a `npm publish` that npm refuses: - `content/docs/deployment/cli.mdx` scaffolder-routing table, "Publishable?" - `content/docs/deployment/cli.mdx` `#### os create` intro prose ("publishable") - `content/docs/plugins/index.mdx` "Which artifact this page means" callout All three are re-derived from the generator (`packages/cli/src/commands/create.ts` `pluginDirName` / `pluginPackageName` / the standalone `private: true`), not from the ruling text. The "Publishable?" column keeps discriminating between the two scaffolders: the `os init -t plugin` cell is "No, and no flag lifts it"; the `os create plugin` cell is "Only with --in-repo". Claude-Session: https://claude.ai/code/session_01DapQyvYrFb1MxSYe7BL2nt Co-authored-by: Claude <noreply@anthropic.com>
1 parent 94c9302 commit 57fb801

2 files changed

Lines changed: 16 additions & 6 deletions

File tree

content/docs/deployment/cli.mdx

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,8 @@ Scaffolds a new ObjectStack project with configuration, TypeScript setup, and in
102102

103103
| The word `plugin` in | Names | What it emits | Built by | Publishable? | Read next |
104104
|:---------------------|:------|:--------------|:---------|:-------------|:----------|
105-
| `os init <name> -t plugin` | A **metadata package** — declarative objects another stack loads, no kernel code | `objectstack.config.ts` whose manifest declares `type: 'plugin'`, plus `src/objects/*.object.ts` | `objectstack compile` (its `build` script) | **No** — the emitted `package.json` is `private: true` | [`os init`](#os-init) below, and [Object Metadata](/docs/data-modeling/objects) for the objects it holds |
106-
| `os create plugin <name>` | A **kernel code plugin** — TypeScript implementing the kernel `Plugin` contract | `src/index.ts` exporting a `Plugin` with `init` / `destroy` | `tsc` (its `build` script) | **Yes** — a publishable `@objectstack/plugin-<name>` package | [`os create`](#os-create) below, then [Plugin Anatomy](/docs/plugins/anatomy) and [Plugin Development](/docs/plugins/development) |
105+
| `os init <name> -t plugin` | A **metadata package** — declarative objects another stack loads, no kernel code | `objectstack.config.ts` whose manifest declares `type: 'plugin'`, plus `src/objects/*.object.ts` | `objectstack compile` (its `build` script) | **No** — the emitted `package.json` is `private: true`, and no flag lifts it | [`os init`](#os-init) below, and [Object Metadata](/docs/data-modeling/objects) for the objects it holds |
106+
| `os create plugin <name>` | A **kernel code plugin** — TypeScript implementing the kernel `Plugin` contract | `src/index.ts` exporting a `Plugin` with `init` / `destroy` | `tsc` (its `build` script) | **Only with `--in-repo`**the default standalone emission is an unscoped `plugin-<name>` marked `private: true`; `--in-repo` emits a publishable `@objectstack/plugin-<name>` | [`os create`](#os-create) below, then [Plugin Anatomy](/docs/plugins/anatomy) and [Plugin Development](/docs/plugins/development) |
107107

108108
Every page under [Plugins & Packages](/docs/plugins) teaches the **kernel code plugin**, so
109109
`os create plugin` is the scaffolder those pages mean — `os init -t plugin` will not give
@@ -1334,7 +1334,7 @@ third-party extension primitive, authored as `src/skills/<name>.skill.ts` with
13341334
#### `os create`
13351335

13361336
Scaffolds a **standalone** **kernel code** plugin project (the `Plugin` contract,
1337-
built by `tsc`, publishable; *not* the **metadata package** `os init -t plugin` emits — see
1337+
built by `tsc`; *not* the **metadata package** `os init -t plugin` emits — see
13381338
[Which scaffolder?](#os-init)) into the current directory:
13391339

13401340
```bash
@@ -1363,6 +1363,14 @@ published semver ranges pinned to the version of the CLI that generated it, and
13631363
the emitted `tsconfig.json` is self-contained, so the project installs and
13641364
builds anywhere — a workspace around it is neither needed nor assumed.
13651365

1366+
That manifest is named `plugin-<name>`**unscoped** — and carries
1367+
`"private": true`, because `@objectstack` is a scope the developer this command
1368+
scaffolds for cannot publish to: an accidental `npm publish` is refused loudly
1369+
instead of being aimed at a namespace you do not own. To publish it yourself,
1370+
rename it under a scope you control and drop that flag. Only `--in-repo` below
1371+
emits a scoped, publishable `@objectstack/plugin-<name>`, and it lands under
1372+
`packages/plugins/` where every sibling genuinely carries that scope.
1373+
13661374
**Options:**
13671375
- `-d, --dir <directory>` — Write the project here instead of `./<name>`
13681376
- `--in-repo` — Scaffold **inside an ObjectStack monorepo checkout** instead

content/docs/plugins/index.mdx

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,11 @@ Plugins follow a strict three-phase lifecycle (`init()` → `start()` → `destr
7777

7878
<Callout type="info">
7979
**Which artifact this page means.** Every plugin taught here is a **kernel code
80-
plugin** — TypeScript implementing the `Plugin` contract, built by `tsc`, published as
81-
`@objectstack/plugin-<name>`. That is what `os create plugin` scaffolds. If what you
82-
want instead is a **metadata package** — declarative objects another stack loads, with
80+
plugin** — TypeScript implementing the `Plugin` contract, built by `tsc`. That is
81+
what `os create plugin` scaffolds: by default an unscoped `plugin-<name>` package
82+
marked `"private": true`, or a publishable `@objectstack/plugin-<name>` under
83+
`--in-repo` inside a checkout of the ObjectStack monorepo. If what you want instead
84+
is a **metadata package** — declarative objects another stack loads, with
8385
no kernel code — the scaffolder is `os init <name> -t plugin`, and
8486
[Which scaffolder?](/docs/deployment/cli#os-init) routes between the two by artifact
8587
rather than by the word `plugin`, which the CLI spells the same for both.

0 commit comments

Comments
 (0)