objectstack-ai
diff --git a/‎.changeset/21325-generate-binds-from-stack.md‎
Lines changed: 39 additions & 0 deletions b/‎.changeset/21325-generate-binds-from-stack.md‎
Lines changed: 39 additions & 0 deletions
diff --git a/‎content/docs/deployment/cli.mdx‎
Lines changed: 52 additions & 29 deletions b/‎content/docs/deployment/cli.mdx‎
Lines changed: 52 additions & 29 deletions
diff --git a/‎packages/cli/README.md‎
Lines changed: 1 addition & 1 deletion b/‎packages/cli/README.md‎
Lines changed: 1 addition & 1 deletion
@@ -0,0 +1,39 @@
+---
+'@objectstack/cli': minor
+---
+
+fix(cli)!: `objectstack generate` binds a view, flow, action or app to an object (and an action to a flow) that you name or that the stack declares, never to one derived from the new item's name, and every scaffold passes `objectstack validate`, `objectstack build` and `objectstack lint` with zero findings
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a change to which `objectstack generate` invocations write a scaffold, and to what the scaffolds contain. No authorable key, spelling, export or stored shape moves: every schema the scaffolds are written against parses exactly what it parsed, the files `objectstack generate` wrote earlier are untouched and still load, and no stored row is read or rewritten. What is narrowed is the command's own argument handling, which no ledger entry can rewrite: the object a scaffold should have bound is the author's to say, which is the whole point of the change. The other categories are closed on facts: the package publishes (not `unpublished`); no ADR-0087 id covers a CLI argument, and this diff adds none (not `registered` / `already-registered`); and the change is command behaviour, not a declaration (not `runtime-interface-only` / `type-surface-only`). -->
+
+**BREAKING**: this narrows which `objectstack generate` invocations write a file. It ships as `minor` under the launch-window convention for narrowings. No export or published type changes.
+
+**Why.** `view`, `flow`, `action` and `app` scaffolds took the object they bind from their own name, and an action took its flow the same way. On a fresh `npm create objectstack` project holding `project` and `task`, `objectstack generate flow task_done` wrote a flow triggered by an object called `task_done` that nothing declares (a flow that never fires) and reported success, while `objectstack generate action complete_task` and `objectstack generate app tasks` were refused, because no object was called `complete_task` or `tasks`. Nothing let the author name the object they meant.
+
+**New options.**
+
+- `--object <object>` names the object a `flow`, `action` or `app` binds, as the stack declares it or without the namespace prefix (`--object task` binds `tasks_app_task` under `namespace: 'tasks_app'`). Without it, the scaffold binds the stack's only object.
+- `--flow <flow>` names the flow an `action` runs. Without it, the action runs the stack's only flow.
+
+**What is now refused, with nothing written.** In each case the command names what the stack declares and the command to run instead.
+
+- A `flow`, `action` or `app` with no `--object` in a stack that declares no object, or several.
+- `--object` or `--flow` naming nothing the stack declares.
+- An `action` with no `--flow` in a stack that declares no flow, or several.
+- A `view` whose name is not an object the stack declares. A view is still named after the object it binds: `objectstack generate view task` writes the views of `tasks_app_task`.
+- Any of these four outside a project, where there is no config and so no stack to check the binding against.
+- `--object` or `--flow` on a type that takes neither (`object`, `dashboard`, `skill`, `picklist`, and the `types`, `client` and `migration` routes), instead of reading as honoured.
+
+**What the scaffolds now write.** Each was measured adding at least one finding to `os validate`, `os build` or `os lint`, and now adds none.
+
+- `object`: the record's title field (`name`) and no `description` field. Nothing read the `description` field, so `field-no-consumers` reported it on every generated object as soon as the project held any view, flow, action, app, dashboard or skill.
+- `view`: no container `name` or `label`. The container is registered under its `object`, so `name` could only restate that key or contradict it, and no reader reaches a container's `label`. Both were `liveness-dead-property` warnings. The list now carries the `label` that `os lint` requires (`required/label` was an error). Its columns are every field the bound object declares, and it is sorted by the object's title field. It used to show a fixed `name` column, which an object without a `name` field refused.
+- `flow`: `status: 'active'` in place of `'draft'`. A draft flow already fires its trigger (only `obsolete` and `invalid` disable one), so the runtime behaviour is unchanged. `flow-draft-status-ambiguous` warned on every scaffold.
+- `action`: `locations: ['record_header']`. With no placement, `action-no-placement` warned that the button renders nowhere.
+- `app`: its navigation entry opens the bound object and is labelled with that object's plural label.
+
+**What to write instead.** Name the object a flow, action or app binds, for example `objectstack generate flow task_done --object task`. Name the flow an action runs when the stack has more than one, for example `objectstack generate action complete_task --object task --flow task_done_flow`. Run the command in the project's directory. Generate a view under the name of an object the stack declares.
+
+**Unchanged.** `objectstack generate object`, `dashboard`, `skill` and `picklist`, and every name, namespace, parse and import check in front of the bindings. Files generated by earlier releases are not touched.
@@ -32,15 +32,16 @@ This scaffolds a working project with `objectstack.config.ts`, a sample object,
 ### Add more metadata
 
 ```bash
-os generate object customer    # Add a Customer object
-os generate flow customer      # Add an automation flow on it
-os generate action customer    # Add an action on it that runs the flow
+os generate object customer                          # Add a Customer object
+os generate flow customer_changed --object customer  # Add an automation flow on it
+os generate action approve --object customer         # Add an action on it that runs the flow
 ```
 
 Each command writes a file and its export line, and the starter's config already
 wires every directory they write into, so all three are part of the stack. The
-flow and the action bind to the object named like them, which is why the object
-comes first: an action bound to an object the stack does not declare is refused.
+flow and the action bind to the object `--object` names, which is why the object
+comes first: a scaffold whose object the stack does not declare is refused, with
+nothing written. The action runs the stack's only flow.
 
 ### Launch the dev server
 
@@ -1440,10 +1441,30 @@ either. A name in the legacy `<namespace>__<name>` form (`order__line`) is
 refused, because no prefix makes it one `os validate` accepts. The namespace is
 read from the loaded config, the same place `os validate` reads it from. If a
 config exists but does not load, the command refuses and writes nothing.
-Without a `namespace` (or without a config), nothing is prefixed. A view's own
-`name` is the object it binds to, prefix included, because the server registers
-a view under that object and refuses one whose `name` says otherwise. Nothing
-else a scaffold names (an action's, flow's or app's own `name`) is prefixed.
+Without a `namespace` (or without a config), nothing is prefixed. Nothing else a
+scaffold names (an action's, flow's or app's own `name`) is prefixed.
+
+**What a scaffold binds comes from you or from the stack, never from its
+name.** A `view`, `action`, `flow` or `app` scaffold refers to metadata the
+project already has, and each reference is checked against the stack the
+config loads before anything is written:
+
+- A **view** is named after the object it binds: `os g view customer` writes
+  the views of the object `os g object customer` writes, prefix included. The
+  container carries no `name` or `label` of its own (the server registers it
+  under its object), and its list shows every field the object declares, under
+  a `list.label` that `os lint` requires.
+- A **flow**, **action** or **app** binds the object you name with
+  `--object` — as declared (`my_app_customer`) or without the namespace prefix
+  (`customer`). Without `--object`, it binds the stack's only object.
+- An **action** runs the flow you name with `--flow`, or the stack's only flow.
+
+When the stack declares none, or several and you named none, or the one you
+named is not declared, the command refuses, lists what the stack does declare,
+and writes nothing: which object a scaffold acts on is yours to say. Outside a
+project (no config) a scaffold that binds is refused too, because there is no
+stack to check it against. `--object` and `--flow` on a type that takes neither
+are refused rather than ignored.
 
 **Every scaffold reaches the stack, or the command says it does not.** The
 `objectstack.config.ts` that `os init` writes for the `app` and `plugin`
@@ -1464,29 +1485,29 @@ After writing, `os g` loads the config again and says which of these holds:
   as it was, and the command prints the import and the `defineStack` key that
   wire the directory.
 - **Refused**: the config loaded before the command wrote anything and no
-  longer loads with the new file in place, because the stack refuses it. Two
-  examples are an action or app bound to an object nobody declared, and a flow
-  in a stack whose `requires` lacks `triggers` or `automation` (`defineStack`
-  refuses a record-change flow without both). The command removes what it
-  wrote, so the project is as it was, and exits 1 with the stack's own reason.
-  Generate the object first (`os g object customer`), then what binds to it,
-  and declare `requires: ['automation', 'triggers']` before `os g flow`.
+  longer loads with the new file in place, because the stack refuses it — for
+  example a flow in a stack whose `requires` lacks `triggers` or `automation`
+  (`defineStack` refuses a record-change flow without both). The command
+  removes what it wrote, so the project is as it was, and exits 1 with the
+  stack's own reason. Declare `requires: ['automation', 'triggers']` before
+  `os g flow`.
 
 `os g` never edits `objectstack.config.ts`: the config is yours, and the
 command only loads it.
 
 ```bash
-os g object customer        # Generate a Customer object
-os g view customer          # Generate a Customer list view
-os g action customer        # Generate an action on Customer records
-os g flow customer          # Generate a flow that runs when a Customer changes
-os g dashboard sales        # Generate a dashboard
-os g app customer           # Generate an app whose navigation opens Customer
-os g skill lead_qual        # Generate an AI skill
-os g picklist industry      # Generate a shared option list select fields name
-
-os g object task -d lib/    # Override target directory
-os g object task --dry-run  # Preview without writing
+os g object customer                          # Generate a Customer object
+os g view customer                            # Generate the Customer list view
+os g flow customer_changed --object customer  # Generate a flow that runs when a Customer changes
+os g action approve --object customer         # Generate an action on Customer records that runs the flow
+os g dashboard sales                          # Generate a dashboard
+os g app sales --object customer              # Generate an app whose navigation opens Customer
+os g skill lead_qual                          # Generate an AI skill
+os g picklist industry                        # Generate a shared option list select fields name
+
+os g action escalate --object customer --flow customer_changed_flow  # Name the flow when there are several
+os g object task -d lib/                      # Override target directory
+os g object task --dry-run                    # Preview without writing
 ```
 
 **Available types:**
@@ -1554,9 +1575,11 @@ the rules a JSON Schema can express and names the rest under
 **Options:**
 - `-d, --dir <directory>` — Override target directory
 - `--dry-run` — Preview without writing files
+- `--object <object>` — The object a `flow`, `action` or `app` binds; default: the stack's only object
+- `--flow <flow>` — The flow an `action` runs; default: the stack's only flow
 
 **What it does:**
-1. For a type that names an object (`object`, `view`, `action`, `flow`, `app`), reads `manifest.namespace` from the project config (`objectstack.config.ts`, `.js` or `.mjs`) and prefixes the object name with it (see above)
+1. For a type that names an object (`object`, `view`, `action`, `flow`, `app`), reads `manifest.namespace` from the project config (`objectstack.config.ts`, `.js` or `.mjs`) and prefixes the object name with it, and resolves every object or flow the scaffold binds against the stack that config loads (see above)
 2. Creates the TypeScript file — an `object` declared with `ObjectSchema.create({ … })`, the same shape the `os init` templates write; a `skill` declared with `defineSkill({ … })`; a `picklist` declared with `definePicklist({ … })`, which a select field names with `Field.select({ picklist: 'NAME' })` in place of its own `options`, and which the server resolves into that field's `options`; the other types as typed literals (`UI.View`, `UI.Action`, `Automation.Flow`, `UI.Dashboard`, `UI.App`)
 3. Creates or updates the barrel `index.ts` in the target directory
 4. Shows a hint to run `objectstack validate`
@@ -2352,7 +2375,7 @@ os g object contact
 os g object opportunity
 
 # 3. Add business logic: a flow that runs when an opportunity changes
-os g flow opportunity
+os g flow opportunity_changed --object opportunity
 
 # 4. Validate everything: each file `os g` wrote is counted and checked
 os validate
 
@@ -21,7 +21,7 @@ os init my-app
 # Generate metadata
 os generate object task
 os generate view task
-os generate flow task
+os generate flow task_changed --object task
 
 # Validate configuration
 os validate