@adobe/data-ai 0.9.91 → 0.9.93

package/README.md

@@ -11,46 +11,95 @@ It installs two things:
 - **skills** — `build-*` commands that scaffold features and applications.
 - **rules** — the path-scoped conventions those skills follow while building.
 
-> **For the installing agent:** find the block below that matches your host
-> (Claude Code or Cursor/other), run its commands, and stop. Each install owns a
-> namespaced folder and is a clean wipe-and-recopy, so re-running is also how you
-> **update** — it never touches files you authored.
+The **rules** are the part that evolves often, so `install` pins the package and
+re-copies them automatically on every install: bump the version and they refresh —
+no manual step, no committed diff, no hand-editing.
 
-## Install — Claude Code
+## Quick start
 
-Skills load as a marketplace plugin; rules install into the project. Run these
-three from a shell (agent-runnable):
+From your project folder root:
+
+**1. Install** — one command:
 
 ```
-claude plugin marketplace add adobe/data --scope project
-claude plugin install adobe-data-ai@adobe-data-skills --scope project
 npx @adobe/data-ai@latest install
 ```
 
-In an interactive Claude session you can instead use the slash-command form of
-the first two — `/plugin marketplace add adobe/data` then
-`/plugin install adobe-data-ai@adobe-data-skills` — but an agent driving a shell
-should use the `claude plugin …` commands above (slash commands aren't
-shell-runnable).
+*(Claude Code only:* also add the skills plugin once — see
+[Claude Code](#claude-code--add-the-skills-plugin-one-time). Cursor/Codex need
+nothing extra; `install` copies their skills.*)*
+
+**2. Restart your AI agent** so it loads the newly installed skills and rules.
+
+**3. Create an application** — ask your agent:
+
+```
+/build-application <a description of the app you want>
+```
+
+That's the whole flow. Everything below explains what `install` does and the
+other build skills available.
+
+## What `install` does
+
+`install` does two things: it **copies the bundle now** (rules →
+`.claude/rules/adobe-data-ai/`, and for Cursor/Codex skills →
+`.agents/skills/adobe-data-ai/`), and it **wires the repo so future installs
+self-update**, editing your `package.json` and `.gitignore` to:
 
-- Skills → the `adobe-data-ai` plugin. **Update:** `claude plugin update adobe-data-ai`.
-- Rules → `.claude/rules/adobe-data-ai/`. **Update:** re-run `npx @adobe/data-ai@latest install`.
+1. pin `@adobe/data-ai` in `devDependencies` at the **exact version it just
+   resolved** (never a range, so a later install can't silently pull an
+   unreviewed release);
+2. add `data-ai install` to **your own** `postinstall` script (chaining if one
+   exists) — it must be *your* script: pnpm does not run a dependency's lifecycle
+   scripts, so a `postinstall` shipped inside the package would silently not fire;
+3. gitignore the managed bundle folders.
 
-## Install — Cursor (and Codex / other `.agents` agents)
+The copied files are regenerated artifacts — never committed, never edited in
+place. The wiring is idempotent, so re-running is harmless; with `--global` or in a
+directory with no `package.json`, `install` just copies (no wiring).
 
-One command installs both:
+After that first run, sync your lockfile with a normal install (`pnpm install`) so
+the pinned dev-dependency is recorded; from then on every install refreshes the
+bundle via the postinstall.
+
+**Why `@latest` for the first command but a pinned version afterward?** The one
+command you type is a one-time, human-initiated bootstrap, so `@latest` is fine
+(the same posture as `npm create …@latest`). The part that *repeats* — every
+teammate's and CI's install — runs from the **exact version `install` pinned into
+your `devDependencies`**, never a moving tag, so no unreviewed release ever
+auto-executes. Pinning happens where it matters, automatically.
+
+**Update:** bump the `@adobe/data-ai` version in `package.json` and install again.
+That's it.
+
+### Claude Code — add the skills plugin (one time)
+
+Claude Code loads skills from a marketplace plugin, not from `.claude/skills/`, so
+its skills are a separate one-time install (the `install` step above already
+handles the rules for Claude Code):
 
 ```
-npx @adobe/data-ai@latest install
+claude plugin marketplace add adobe/data --scope project
+claude plugin install adobe-data-ai@adobe-data-skills --scope project
 ```
 
-- Skills → `.agents/skills/adobe-data-ai/`.
-- Rules → `.claude/rules/adobe-data-ai/`.
-- **Update:** re-run the same command.
+(Interactive sessions can use `/plugin marketplace add adobe/data` then
+`/plugin install adobe-data-ai@adobe-data-skills`.) **Update the skills:**
+`claude plugin update adobe-data-ai`. Cursor/Codex need no plugin — `install`
+copies their skills too.
+
+### Just the files, no managed dependency
 
-## Use
+If you don't want the auto-update wiring — a throwaway scaffold, a non-Node repo,
+or you'd rather commit the bundle and update it on your own schedule — run
+`install` where it can't wire (no `package.json`, or pass `--global`), or simply
+delete the `postinstall`/dev-dependency lines it added. Re-running `install` is
+always a clean wipe-and-recopy; you then update by re-running it yourself.
 
-Ask your agent to run a build command — skills are available by name:
+## Build skills
+
+Step 3 above uses `build-application`; the skills are available by name:
 
 - **`build-application`** — build a whole app: a base feature that hosts
   lazily-loaded peer features.
@@ -66,15 +115,16 @@ by name when you want a single phase or a specialized flow: `build-data`,
 in subagents), `review` (audit output against the rules), and `structure`
 (reason about layout).
 
-## One-liner: install + build an app
-
-Paste one of these into a shell, replacing the quoted text with your own app
-description. It installs the bundle, then runs `build-application` headlessly on
-your prompt.
+## One-liner: install + build an app (headless)
 
-This presumes you are already running the agent within the directory you want to use as your project root.
+Paste this into an agent already running in your project root, replacing the
+quoted text with your own app description. It installs the bundle, then runs
+`build-application` on your prompt:
 
 ```
-Find the @adobe/data-ai package on npmjs and then install it in the current directory.
-Next use it's /build-application skill to build <prompt here>
+Set up @adobe/data-ai in the current directory: run
+`npx @adobe/data-ai@latest install` (this copies the bundle and pins the exact
+version so rules auto-update on every install). On Claude Code also add the
+skills plugin per the package README. Then use its /build-application skill to
+build <prompt here>
 ```

package/bin/cli.mjs

@@ -157,6 +157,78 @@ version on every install. Package: <https://www.npmjs.com/package/${PKG_NAME}>
     return file;
 }
 
+// Wire the consumer repo for auto-updating installs (part of `install`, not a
+// separate step). Idempotently:
+//   1. pins `@adobe/data-ai` in devDependencies (exact version — never a range,
+//      so an install can't silently pull an unreviewed release),
+//   2. adds `data-ai install` to the consumer's OWN `postinstall` (a dependency's
+//      lifecycle script does NOT run under pnpm, so it must live here), and
+//   3. gitignores the managed, regenerated bundle folders.
+// After this, bumping the pinned version and re-installing recopies the bundle —
+// no manual step, no committed diff. Skips gracefully with a note when there is
+// no package.json (the bundle is still copied; the repo just isn't auto-wired).
+const MANAGED_GITIGNORE = [
+    `# ${PKG_NAME} — managed, regenerated on install; do not edit or commit`,
+    ".claude/rules/adobe-data-ai/",
+    ".claude/rules/adobe-data-ai-bootstrap.md",
+    ".agents/skills/adobe-data-ai/",
+];
+
+function wireManagedUpdates(base) {
+    const pkgPath = join(base, "package.json");
+    if (!existsSync(pkgPath)) {
+        process.stdout.write(
+            `  (no package.json in ${base} — auto-update not wired; the bundle was still copied.\n` +
+                `   Add one, re-run install to wire it, or re-run manually to update.)\n`,
+        );
+        return;
+    }
+    const consumer = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const changes = [];
+
+    // 1. pinned devDependency
+    consumer.devDependencies ??= {};
+    let pinnedDep = false;
+    if (consumer.devDependencies[PKG_NAME] !== VERSION) {
+        consumer.devDependencies[PKG_NAME] = VERSION;
+        changes.push(`devDependencies["${PKG_NAME}"] = "${VERSION}" (exact)`);
+        pinnedDep = true;
+    }
+
+    // 2. own postinstall runs the installer (chain if one already exists)
+    consumer.scripts ??= {};
+    const INSTALL = "data-ai install";
+    const post = consumer.scripts.postinstall;
+    if (!post) {
+        consumer.scripts.postinstall = INSTALL;
+        changes.push(`scripts.postinstall = "${INSTALL}"`);
+    } else if (!post.includes(INSTALL)) {
+        consumer.scripts.postinstall = `${post} && ${INSTALL}`;
+        changes.push(`scripts.postinstall += " && ${INSTALL}"`);
+    }
+    if (changes.length) writeFileSync(pkgPath, JSON.stringify(consumer, null, 2) + "\n");
+
+    // 3. gitignore the managed bundle folders
+    const giPath = join(base, ".gitignore");
+    const gi = existsSync(giPath) ? readFileSync(giPath, "utf8") : "";
+    if (!gi.includes(MANAGED_GITIGNORE[0])) {
+        const sep = gi === "" ? "" : gi.endsWith("\n") ? "\n" : "\n\n";
+        writeFileSync(giPath, gi + sep + MANAGED_GITIGNORE.join("\n") + "\n");
+        changes.push(".gitignore += managed bundle paths");
+    }
+
+    for (const c of changes) process.stdout.write(`  wired: ${c}\n`);
+    if (!changes.length) process.stdout.write("  auto-update already wired\n");
+    // Adding/repinning the dev-dependency leaves the lockfile out of sync until a
+    // normal install records it (and CI with a frozen lockfile would fail until then).
+    if (pinnedDep) {
+        process.stdout.write(
+            "\nNext: run your package manager's install to sync the lockfile\n" +
+                "  pnpm install    # or npm install / yarn\n",
+        );
+    }
+}
+
 function parseArgs(argv) {
     const positional = [];
     const flags = new Set();
@@ -177,11 +249,17 @@ Install the architecture skills + rules for Cursor, Codex, and other agents.
 same way for every agent — see README.)
 
 Usage:
-  npx ${PKG_NAME}@latest install [options]
+  npx ${PKG_NAME}@latest install   # copy the bundle AND wire auto-updates (default)
   npx ${PKG_NAME}@latest list
 
 Commands:
-  install   Skills → .agents/skills/${BUNDLE}/, rules → .claude/rules/${BUNDLE}/ (default).
+  install   Copy the bundle (skills → .agents/skills/${BUNDLE}/, rules →
+            .claude/rules/${BUNDLE}/) AND wire this repo for auto-updating installs:
+            pin ${PKG_NAME} in devDependencies (exact), add \`data-ai install\` to the
+            repo's own postinstall, and gitignore the managed bundle folders. Run once;
+            thereafter a plain install refreshes the bundle and bumping the pinned
+            version updates it. Skips the wiring (copies only) with \`--global\` or when
+            there's no package.json.
   list      Print the skills bundled in this package.
 
 Options:
@@ -229,6 +307,10 @@ function main() {
     process.stdout.write(`  ${skills.length} skills → ${skillsDir}\n`);
     process.stdout.write(`  ${ruleCount} rules  → ${rulesDir}\n`);
     process.stdout.write(`  bootstrap → ${bootstrapFile}\n`);
+
+    // A project install also wires the repo for auto-updating installs (idempotent).
+    // A global install has no consumer package.json to wire, so it only copies.
+    if (!flags.has("global")) wireManagedUpdates(base);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.91",
+  "version": "0.9.93",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -29,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.9.91"
+    "@adobe/data": "0.9.93"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.91"
+    "@adobe/data": "0.9.93"
   },
   "license": "MIT",
   "scripts": {

package/skills/build-app-entry/SKILL.md

@@ -9,7 +9,7 @@ output: app
   plugin, so all schemas coexist, persist, and sync while the base type stays decoupled.
 - The base reaches a peer only through a lazy element wrapper (dynamic import), so peers
   load on demand.
-- The entry point creates the live database from `FeatureDatabase.plugin` (the base
+- The entry point creates the live database from `MainService.plugin` (the base
   feature's assembled database — see `features/services/main-service/index.md`) and mounts the root UI.
 
 See `features/index.md` (one-app-many-features) for the wiring rules.

package/skills/build-data/SKILL.md

@@ -8,14 +8,14 @@ output: feature
 Create the feature's `data/` layer (pure spec; depends on nothing but `@adobe/data`
 and other `data/` declarations):
 
-- one namespace folder per data type — `<type>/{<type>.ts, schema.ts, public.ts, <helper>.ts}`;
+- one namespace folder per data type — `<type>/{<type>.ts, public.ts, <helper>.ts}` (+ `schema.ts` only when a runtime boundary needs it);
 - `data/state/` — the `State` aggregate plus its pure transforms/derivations.
 
 **Always create `data/state/`** — even for a shell feature whose only field is a
 boolean or enum. A feature with ECS resources/transactions but no `State` is
 incomplete: the transaction must wrap a pure transform, not invent the logic. In rare circumstances, there may be no real state in a feature in which case the state type = {}
 
-The schema is the single source of truth; the type derives from it (`Schema.ToType`).
+The hand-authored type in `<type>.ts` is the source of truth. The schema is optional up front — add `schema.ts` only when a runtime boundary (persistence, wire, or an ECS component/resource) needs one, write it to match the type, and pin it with `type _Pin = Assert<Equal<Schema.ToType<typeof schema>, <Type>>>` so it cannot drift. `Schema.ToType` is used only in that assertion, never as the exported type.
 Helpers are pure and unit-tested. Run this first — every other layer imports `data/`.
 
 The how is in the auto-loading rules: `features/data/index.md`, `features/data/state.md`, and

package/skills/build-systems/SKILL.md

@@ -12,7 +12,7 @@ Create `services/main-service/system-database/system-database.ts`: `Database.Plu
 Database.Plugin.combine(<currentTop>.plugin, scheduler), systems })` — combine `scheduler` with the
 feature's **current top** main-service layer (`ActionDatabase` / `ServiceDatabase` / `ComputedDatabase`,
 whichever it built), never a hardcoded `ComputedDatabase`, so systems *and* any services/actions
-compose into the one `FeatureDatabase`. The `systems`
+compose into the one `MainService`. The `systems`
 map is declared **inline** (see `features/services/main-service/systems.md` — inline is required for `db` to be
 typed and for system-name inference; a `systems/` folder is optional, only for extracted
 per-frame body helpers).