octwin-cli 0.8.8 → 0.8.9

package/CHANGELOG.md

@@ -5,6 +5,30 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.8.9] - 2026-09-07
+
+### Added
+- **Every authenticated request now says which CLI and which capability reference you are on.**
+  Two headers off `authHeaders` — `x-octwin-cli` and `x-octwin-kb` (the `content_hash` of your
+  pulled reference) — so `deploy`, `validate --remote`, `status`, `chat`, `logs` and `memos` all
+  carry them, from one place. The platform stores them against your deploy token and shows them in
+  the console (Settings → API tokens, and Platform → Packs → Feedback → Author tooling for us).
+
+  **Why the platform needs this from you.** Almost every field report so far turned out to be
+  either already fixed in a newer CLI or written against a stale reference — three very different
+  answers that look identical without these two facts. They were captured on `octwin feedback`
+  only, so an author who never filed a report was invisible. Nothing here affects auth: a request
+  that sends neither header authenticates exactly as before, and a value that could not travel as
+  a header (a corrupt `package.json`, an interrupted pull) is dropped rather than sent.
+
+### Fixed
+- **The upgrade notice was skipped under `npx` — silencing the population most likely to be
+  stale.** The premise was that "`@latest` already resolves the newest", which holds for
+  `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` the docs put in front of
+  external developers: npm serves that from its **cache**, so it can be arbitrarily old. Under
+  `@latest` the check is self-silencing anyway (you are already newest), so keeping it costs
+  nothing — only the advice line differs, because there is no global install to reinstall.
+
 ## [0.8.8] - 2026-09-06
 
 ### Added

package/dist/index.js

@@ -69,6 +69,7 @@ import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding }
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
 import { yamlLineOf } from './lib/yaml-pos.js';
 import { localhostFamilyHint } from './lib/net-hint.js';
+import { authHeaders as buildAuthHeaders } from './lib/client-headers.js';
 import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from './lib/builtin-check.js';
 import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
 import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
@@ -542,9 +543,8 @@ async function latestPublishedVersion() {
     }
 }
 /** True when running via `npx` — the CLI's own file lives in npx's cache dir, or npm
- *  ran it as `npm exec`. Under npx there is no persistent install to upgrade
- *  (`@latest` already resolves the newest), so an upgrade notice would be
- *  misleading — stay silent. The notice is for a GLOBAL install (`npm i -g`). */
+ *  ran it as `npm exec`. Only the ADVICE changes on this: there is no global install
+ *  to upgrade, so the fix is to pin `@latest` rather than to reinstall. */
 function isNpx() {
     try {
         return fileURLToPath(import.meta.url).includes('_npx') || process.env.npm_command === 'exec';
@@ -555,23 +555,31 @@ function isNpx() {
 }
 /** A one-line upgrade notice when a newer octwin-cli is published, or [] when current.
  *
- *  Skipped only under npx, where there is genuinely nothing to upgrade. It USED to bail on
- *  `!process.stdout.isTTY` as well, which silently made this the one notice a piped reader never
- *  saw — the opposite of the rule its two siblings already carry in their docblocks, and measured
- *  2026-08-26: with a newer version cached, `octwin whoami | tail` printed the KB nudge and not
- *  this one. An agent driving the CLI cannot notice an outdated CLI on its own, so it is exactly
- *  the reader that needs telling. One line on stderr, so piped stdout stays clean either way.
+ *  Gated on NOTHING. It USED to bail on `!process.stdout.isTTY`, which silently made this the one
+ *  notice a piped reader never saw — the opposite of the rule its two siblings already carry in
+ *  their docblocks, and measured 2026-08-26: with a newer version cached, `octwin whoami | tail`
+ *  printed the KB nudge and not this one. An agent driving the CLI cannot notice an outdated CLI on
+ *  its own, so it is exactly the reader that needs telling. One line on stderr, so piped stdout
+ *  stays clean either way.
+ *
+ *  IT ALSO USED TO BAIL UNDER npx, on the premise that "`@latest` already resolves the newest".
+ *  That premise holds for `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` that
+ *  `BACKLOG-decided.md` and the authoring skill both put in front of external developers — npm
+ *  serves that from its cache, so it can be arbitrarily old and was the ONE population this
+ *  notice never reached. Under `@latest` the check is self-silencing anyway (`VERSION` is already
+ *  the newest, so `isNewer` is false), which is why keeping it costs nothing and only the advice
+ *  line has to differ: there is no global install to reinstall.
  *
  *  Never throws — a version check must never break a command. */
 async function outdatedNotice() {
-    if (isNpx())
-        return [];
     try {
         const latest = await latestPublishedVersion();
         if (latest && isNewer(latest, VERSION)) {
             return [
                 `\n⬆ octwin-cli ${latest} is available (you have ${VERSION}).`,
-                '  Upgrade: npm i -g octwin-cli@latest   (or just use npx octwin-cli@latest)',
+                isNpx()
+                    ? '  You are running via npx, which serves a CACHED copy — pin it: npx octwin-cli@latest'
+                    : '  Upgrade: npm i -g octwin-cli@latest   (or just use npx octwin-cli@latest)',
             ];
         }
     }
@@ -585,6 +593,18 @@ async function outdatedNotice() {
 // catalogs only) describes how to enumerate a catalog so we can EXPLODE it into
 // one file per entry; the PLATFORM supplies it rather than this CLI hardcoding
 // per-catalog knowledge, so a platform that adds a catalog needs no CLI release.
+/**
+ * The pulled reference for THIS run, read once in `main` before any command.
+ *
+ * Two readers need it and both used to reach for the disk themselves: the drift
+ * nudge, and now `authHeaders` (which runs on every request — see the client
+ * report). Reading it once also keeps the corrupt-`index.json` warning below to
+ * one printing.
+ *
+ * `null` = nothing pulled (or unreadable); a non-null row with a null
+ * `content_hash` = pulled, but the identity file did not carry one.
+ */
+let LOCAL_KB = null;
 /** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
  *  (content hash + per-entry index), or null if nothing has been pulled yet. */
 function readLocalKb(packDir) {
@@ -658,8 +678,9 @@ async function fetchKbMeta(t, timeoutMs = 2_000) {
  *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
  *  of the CLI: run only after commands that already hit the platform, so this adds
  *  a single tiny `?meta=1` GET on top of work that was networked anyway. Never
- *  throws — observing must never break a command. No-op until the author has pulled
- *  once (nothing to compare) or if the target can't be resolved.
+ *  throws — observing must never break a command. No-op if the target can't be
+ *  resolved, or until the author has pulled once — nothing pulled is the PLATFORM's
+ *  line to say, on deploy + validate, so that it reaches an old CLI too.
  *
  *  NOT TTY-gated, deliberately. It was, on the reasoning that a nudge is for a
  *  human watching a terminal — but the primary reader of this CLI is now an
@@ -668,10 +689,24 @@ async function fetchKbMeta(t, timeoutMs = 2_000) {
  *  told. It is a single line on stderr, so piped stdout stays clean either way. */
 async function kbStaleNotice(flags) {
     try {
-        const packDir = resolve(flags.dir ?? '.');
-        const local = readLocalKb(packDir);
+        const local = LOCAL_KB;
+        /**
+         * NOTHING PULLED IS NOT THIS OBSERVER'S JOB — it is the PLATFORM's.
+         *
+         * This branch is a no-op, which reads like the bug it used to be, so: the "you have
+         * pulled no reference" line now comes from the platform, on `deploy` and
+         * `validate --remote` (`routes/packs/_cli-advisory.ts`), and that is strictly better
+         * placed. A client-side nudge can only reach a CLI new enough to contain it, and the
+         * authors who have pulled nothing are exactly the ones most likely to be on an old
+         * one. The server answer reaches every CLI.
+         *
+         * Saying it here TOO was measured on 2026-09-07 and rejected: a never-pulled
+         * `validate` printed the same fact three times — the SKIPPED-checks line (which is
+         * the most specific of the three, naming how many checks could not run), the
+         * platform's advisory, and this. Three is how the credible ones stop being read.
+         */
         if (!local?.content_hash)
-            return []; // never pulled → the skill already says to pull
+            return [];
         // URL only, deliberately: the KB poll is anonymous, so requiring a token here would
         // silence the nudge for exactly the authors who most need it. This used to call
         // `resolveTargetOrNull` (url AND token) against the tenant-scoped route, which needs
@@ -1418,14 +1453,16 @@ async function cmdLoginBrowser(url, flags) {
     }
     exitNow(EXIT_STILL_PENDING);
 }
-/** Bearer auth + the optional self-surface overrides, as request headers. */
+/**
+ * Bearer auth + the optional self-surface overrides + this run's client report.
+ *
+ * A thin wrapper so the ~90 call sites stay unchanged while the logic (and its
+ * two omit-don't-placeholder rules) lives in a testable module. The KB hash comes
+ * from `LOCAL_KB`, read ONCE per run in `main` — reading it per request would hit
+ * the disk on every call and could print the corrupt-index warning many times.
+ */
 function authHeaders(t) {
-    const h = { authorization: `Bearer ${t.token}` };
-    if (t.tenant)
-        h['x-octwin-tenant'] = t.tenant;
-    if (t.project)
-        h['x-octwin-project'] = t.project;
-    return h;
+    return buildAuthHeaders(t, { cliVersion: VERSION, kbContentHash: LOCAL_KB?.content_hash ?? null });
 }
 /** Resolve platform url + token (+ optional tenant/project overrides):
  *  flags > env > saved login. Tenant is derived from the token server-side, so
@@ -2581,7 +2618,9 @@ async function cmdFeedback(flags) {
     const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
     const packId = typeof doc?.id === 'string' ? doc.id : die('manifest.yaml must declare a string `id`');
     const packVersion = typeof doc?.version === 'string' ? doc.version : undefined;
-    const kbHash = readLocalKb(packDir)?.content_hash ?? undefined;
+    // `LOCAL_KB` is this run's read of the SAME `--dir`, taken in `main` — so this is the
+    // hash the client report already sent in the headers, not a second opinion about it.
+    const kbHash = LOCAL_KB?.content_hash ?? undefined;
     console.log(`→ Submitting ${Math.round(Buffer.byteLength(report, 'utf8') / 1024)}KB of feedback on ${packId} to ${targetLabel(t)} …`);
     const { status, json } = await apiSend('POST', `${url}/api/self/p/packs/feedback`, {
         pack_id: packId,
@@ -5550,6 +5589,9 @@ async function main() {
     // exit code with 127, so a failing `octwin deploy` in CI reported the wrong thing. Measured
     // 2026-08-26: one pre-command poll exits 1 cleanly, two concurrent ones abort. Awaiting them in
     // turn costs one extra round-trip on an already-networked command and keeps the exit code true.
+    // Read the pulled reference ONCE, here, before anything can ask for it: the drift nudge below
+    // needs its index, and `authHeaders` needs its hash on every request of every command.
+    LOCAL_KB = readLocalKb(resolve(flags.dir ?? '.'));
     const networked = commandTouchesPlatform(command, flags);
     if (networked) {
         PENDING_NOTICES.push(...await kbStaleNotice(flags));

package/dist/lib/client-headers.js

@@ -0,0 +1,80 @@
+/**
+ * What this CLI tells the platform about ITSELF, on every authenticated request.
+ *
+ * ## Why this exists
+ *
+ * A pack built against an old CLI or a stale capability reference is wrong in ways
+ * that look like platform bugs. That is measured, not feared: one author hardcoded
+ * English across all 16 flows of a production pack to work around a bug fixed two
+ * days earlier, and two authors independently filed a CLI bug as platform replica
+ * lag. The platform's own schema says so — `007_pack_feedback.sql` captures
+ * `cli_version` + `kb_content_hash` because "almost every report from the field so
+ * far turned out to be either (a) already fixed in a newer CLI, or (b) written
+ * against a stale capability reference".
+ *
+ * But it captured them on ONE route: `octwin feedback`. `deploy` and `validate`
+ * sent neither, so an author who never filed a report was invisible — and the two
+ * client-side nudges (the npm upgrade check, the KB drift poll) are both blind in
+ * exactly the states that matter most: nothing pulled at all, and `npx`.
+ *
+ * So the report rides the AUTH HEADERS instead. `authHeaders` is the one place
+ * every networked command builds its headers, which is why two lines here cover
+ * deploy, validate, status, chat, logs and memos at once.
+ *
+ * ## Two rules that are not obvious
+ *
+ * **Omit, never send a placeholder.** A missing `x-octwin-kb` means "this author
+ * pulled no reference". A literal `"none"` would be a magic string every reader has
+ * to learn, and it would land in the platform's column as a value that looks like
+ * data.
+ *
+ * **A malformed value is dropped, not sent.** undici THROWS on a header value
+ * containing a newline, and these values come off disk (`package.json`, a pulled
+ * `index.json`) — so an unvalidated pass-through turns a corrupt file into a failed
+ * command. A diagnostic that can break the command it annotates is not a
+ * diagnostic. The platform validates again on its side; that is a bound on what it
+ * stores, not a substitute for this.
+ */
+/** This CLI's version. Read by the platform on every authenticated request. */
+export const HEADER_CLI_VERSION = 'x-octwin-cli';
+/** The `content_hash` of the capability reference the author actually pulled. */
+export const HEADER_KB_HASH = 'x-octwin-kb';
+/**
+ * A semver-ish version safe to put in a header. Deliberately wider than `x.y.z`
+ * (a prerelease tag is a real version) and hard-bounded, because the value comes
+ * from a `package.json` this module does not control.
+ */
+const SAFE_VERSION = /^[0-9A-Za-z.+-]{1,32}$/;
+/**
+ * The published hash shape is 12 hex — `contentHash()` truncates a sha256 — but
+ * the range is loose on purpose: the platform owns that length and may change it,
+ * and a CLI that rejected a longer hash would silence its own report on the very
+ * upgrade it should be reporting.
+ */
+const SAFE_KB_HASH = /^[0-9a-f]{8,64}$/;
+/** The client report as headers — each field omitted when absent or malformed. */
+export function clientReportHeaders(report) {
+    const h = {};
+    if (SAFE_VERSION.test(report.cliVersion))
+        h[HEADER_CLI_VERSION] = report.cliVersion;
+    const kb = report.kbContentHash;
+    if (kb && SAFE_KB_HASH.test(kb))
+        h[HEADER_KB_HASH] = kb;
+    return h;
+}
+/**
+ * Bearer auth + the optional self-surface overrides + the client report.
+ *
+ * The token carries its own tenant (server-side), so the unified `/api/self/**`
+ * surface needs neither tenant nor project in the URL. `tenant`/`project` are kept
+ * only as OPTIONAL overrides (project overrides an unpinned token; a mismatched
+ * override of a pinned token is rejected server-side).
+ */
+export function authHeaders(t, report) {
+    const h = { authorization: `Bearer ${t.token}` };
+    if (t.tenant)
+        h['x-octwin-tenant'] = t.tenant;
+    if (t.project)
+        h['x-octwin-project'] = t.project;
+    return { ...h, ...clientReportHeaders(report) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {