@odla-ai/cli 0.22.0 → 0.23.0

package/README.md

@@ -37,6 +37,26 @@ npx @odla-ai/cli runbook list                                      # what exists
 Reading works for any signed-in developer and needs no `odla.config.mjs` — the
 advice is most useful before there is a project.
 
+Runbooks tell an agent how to operate; PM tells every agent what this project is
+trying to prove, what is active, what was decided, and what is broken. Once the
+app is registered, start each session by reading its doing tasks, open bugs and
+goals, and recent decisions:
+
+```bash
+npx odla-ai pm task list --app <appId> --column doing
+npx odla-ai pm bug list --app <appId> --status open
+npx odla-ai pm goal list --app <appId> --status open
+npx odla-ai pm decision list --app <appId> --limit 20
+```
+
+Read the active task, linked goal, and comments before changing code. Without
+`--app`, list commands span every project the account co-owns, which is the
+right first view when coordinating several efforts; scope every write to the
+exact `appId` from that project's config. PM requires a registered app. Before
+the first provision, use a focused commit/checkpoint, then initialize PM and
+backfill that evidence immediately after registration. Never use a parallel
+status diary or put a secret in PM.
+
 **Runbooks are procedure; JSDoc is API.** What a function takes, returns, and
 guarantees is documented on the export itself, ships in the installed
 `.d.ts`, and renders per package at <https://odla.ai/docs>. A runbook will tell
@@ -93,11 +113,14 @@ npx @odla-ai/cli init --app-id my-app --name "My App"
 ```
 
 For a project you keep working in, install it as a dev dependency so the
-shorter `npx odla-ai` form works and the version is pinned by your lockfile:
+shorter `npx odla-ai` form works. ODLA is under active development: use a normal
+dependency declaration, commit the lockfile, and let `npm ci` reproduce the
+resolved graph:
 
 ```bash
-npm view @odla-ai/cli@0.16.6 version
-npm i -D --save-exact @odla-ai/cli@0.16.6
+npm view @odla-ai/cli version
+npm i -D @odla-ai/cli
+npm ls @odla-ai/cli
 ```
 
 ## Prerequisites
@@ -360,8 +383,8 @@ rolling-window/age-out, quota-backoff, retention/purge, or provider-derived
 mutation-id control. Public health remains aggregate rather than per calendar.
 
 The bundled build/migration skills add a passive pre-ship gate with
-`@odla-ai/security`: after the exact-version availability check, run
-`npm i -D --save-exact @odla-ai/security@0.3.1`, then
+`@odla-ai/security`: install it with a normal development range, commit the
+lockfile, then run `npm i -D @odla-ai/security`, followed by
 `npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
 The passive scan remains a separate binary: it makes no model calls and does
 not execute target code. After explicit redacted-source approval,
@@ -385,12 +408,11 @@ a conservative `Retry-After`. A provider-side `429` uses the sanitized
 carries a bounded `Retry-After` only when the upstream supplied one. The CLI
 does not echo arbitrary response text or silently change the admin-selected
 model.
-Before installing the exact release, require
-`npm view @odla-ai/security@0.3.1 version` to succeed before installation. An
-exact-version `E404` means the release is unavailable, not that the security
-preflight passed, and does not prove the package name is absent. odla's own
-engineering environment uses an equivalent internal gate; customer projects
-should use the published `odla-security` command above.
+Confirm `npm view @odla-ai/security version` succeeds and record the installed
+version from `npm ls @odla-ai/security` with the scan evidence. A registry
+failure blocks the preflight; it is not a clean scan. odla's own engineering
+environment uses an equivalent internal gate; customer projects should use the
+published `odla-security` command above.
 
 For a server-side, commit-pinned review, connect one repository through the
 source-read-only odla GitHub App. The CLI infers `owner/name` from a safe GitHub HTTPS

package/dist/bin.cjs

@@ -1390,6 +1390,7 @@ function chooseIdMode(options, rows) {
 async function appImport(options) {
   const cfg = await loadProjectConfig(options.configPath);
   const out = options.stdout ?? console;
+  const say = options.json ? (line) => out.error(line) : (line) => out.log(line);
   const doFetch = options.fetch ?? fetch;
   const { tenant } = resolveTenant(cfg, options.env);
   const text = options.file === "-" ? (options.readStdin ?? (() => (0, import_node_fs6.readFileSync)(0, "utf8")))() : (0, import_node_fs6.readFileSync)(options.file, "utf8");
@@ -1411,10 +1412,10 @@ ${detail}${more}`);
   }
   const chunks = (0, import_import.planImportChunks)(ops);
   const result = { tenant, rows: ops.length, chunks: chunks.length, committed: 0, duplicate: 0, txIds: [], ignored };
-  if (ignored.length > 0) out.log(`ignoring server-maintained field(s): ${ignored.join(", ")} \u2014 odla-db stamps these on write`);
+  if (ignored.length > 0) say(`ignoring server-maintained field(s): ${ignored.join(", ")} \u2014 odla-db stamps these on write`);
   if (options.dryRun || options.yes !== true) {
     const why = options.dryRun ? "--dry-run" : "no --yes";
-    out.log(`${tenant}: would upsert ${ops.length} row(s) across ${chunks.length} transaction(s) \u2014 nothing written (${why})`);
+    say(`${tenant}: would upsert ${ops.length} row(s) across ${chunks.length} transaction(s) \u2014 nothing written (${why})`);
     if (options.json) out.log(JSON.stringify(result, null, 2));
     return result;
   }
@@ -1623,6 +1624,7 @@ function printPlan(out, verb, pre, opts) {
 async function appTransfer(options) {
   const cfg = await loadProjectConfig(options.configPath);
   const out = options.stdout ?? console;
+  const say = options.json ? (line) => out.error(line) : (line) => out.log(line);
   const doFetch = options.fetch ?? fetch;
   const tenants = bothTenants(cfg);
   const route2 = endpointsFor(options.verb, tenants);
@@ -1643,7 +1645,7 @@ async function appTransfer(options) {
     throw new Error(`pre-flight failed${pre.body.error?.code ? ` (${pre.body.error.code})` : ""}: ${pre.body.error?.message ?? pre.status}`);
   }
   const plan = pre.body;
-  printPlan(out, options.verb, plan, options);
+  printPlan({ log: say }, options.verb, plan, options);
   if (options.verb === "go-live" && !plan.targetEmpty) {
     throw new Error(
       `${route2.target} already has data \u2014 go-live has already happened. Use \`odla-ai app promote --yes\` to push schema and rules, or \`odla-ai app refresh-sandbox --yes\` to pull live back down.`
@@ -1651,7 +1653,7 @@ async function appTransfer(options) {
   }
   if (plan.blockers.length > 0) throw new Error(`cannot ${options.verb}: ${plan.blockers.map((b) => b.message).join("; ")}`);
   if (options.dryRun || options.yes !== true) {
-    out.log(`nothing written (${options.dryRun ? "--dry-run" : "no --yes"})`);
+    say(`nothing written (${options.dryRun ? "--dry-run" : "no --yes"})`);
     if (options.json) out.log(JSON.stringify(plan, null, 2));
     return { ok: true, plan };
   }
@@ -1665,7 +1667,7 @@ async function appTransfer(options) {
     );
     if (res2.status !== 200) throw new Error(`promote failed${res2.body.error?.code ? ` (${res2.body.error.code})` : ""}: ${res2.body.error?.message ?? res2.status}`);
     if (options.json) out.log(JSON.stringify(res2.body, null, 2));
-    else out.log(`${route2.target}: promoted ${(res2.body.applied ?? []).join(", ")}`);
+    else say(`${route2.target}: promoted ${(res2.body.applied ?? []).join(", ")}`);
     return { ok: true, plan, result: res2.body };
   }
   const res = await api(
@@ -1684,7 +1686,7 @@ async function appTransfer(options) {
     doFetch
   );
   if (res.status !== 200) throw new Error(`${options.verb} failed${res.body.error?.code ? ` (${res.body.error.code})` : ""}: ${res.body.error?.message ?? res.status}`);
-  out.log(`${route2.target}: replaced from ${route2.source} (tx ${res.body.destination?.maxTx}, epoch ${res.body.destination?.epoch}) \u2014 connected clients resync automatically`);
+  say(`${route2.target}: replaced from ${route2.source} (tx ${res.body.destination?.maxTx}, epoch ${res.body.destination?.epoch}) \u2014 connected clients resync automatically`);
   if (options.includeFiles) await copyFiles(cfg, token, route2, doFetch, out);
   if (options.json) out.log(JSON.stringify(res.body, null, 2));
   return { ok: true, plan, result: res.body };