@redue/cli 0.0.0-stage → 0.1.0-alpha.3

package/docs/user/receipt-selection-notice.md

@@ -0,0 +1,60 @@
+# Receipt selection correction in alpha.3
+
+**Known affected release: `@redue/cli@0.1.0-alpha.2`. Fixed in
+`@redue/cli@0.1.0-alpha.3`.** No exploit or affected-user count is established.
+REDUE remains an alpha.
+
+If a wrapper persisted a newer outcome but its observer reload notification
+failed, the observer could continue selecting an older passing receipt. Cached
+and synchronized status could then present that older result as CURRENT and
+eligible for reuse. A separate reproduced write-failure window left a new
+immutable outcome recorded while replacing the selected receipt failed.
+
+Until upgraded, do not rely solely on affected CURRENT output to skip checks.
+Run verification when needed and inspect its actual outcome; a successful status
+command is not proof that the latest execution passed.
+
+## What changes
+
+The observer refreshes REDUE-owned receipt selection before publishing status.
+Clients check that a response represents the current readable selection. Missing,
+unreadable, malformed, incompatible, or replaced selection cannot authorize
+reuse. A new client connecting to an alpha.2 observer returns UNVERIFIED and
+asks for a restart, even when the old response says CURRENT.
+
+A small owned pending-update record also withholds applicability after an
+incomplete receipt write. Successful recording clears only that check's pending
+entry. It does not discard another check's incomplete outcome or automatically
+promote an orphaned journal entry. Inspect the failed run and storage error, fix
+the storage problem, then record that check again. An unreadable/malformed pending
+record requires operator inspection; do not delete receipts to obtain green status.
+
+Historical PASS/FAIL and immutable `runs-v1` files remain intact. Stable applicable
+FAIL remains a failure and is never reuse-eligible. This guard tracks owned
+receipt replacement; it does not replace input-content validation or promise an
+atomic decision against concurrent edits/writes.
+
+## Upgrade and restart
+
+From each initialized project, stop its observer before replacing the installation.
+After all observers for that installation have stopped, upgrade it once, then
+restart each observer with its existing configuration and state selection:
+
+```sh
+redue stop
+npm install --global @redue/cli@0.1.0-alpha.3
+redue --version
+redue start
+redue status --sync --json
+```
+
+Use the same npm `--prefix`, project `--config`, and `--state-dir` you already use,
+if customized. On Windows use `npm.cmd`/`redue.cmd` where required by the existing
+shell policy. Stop all observers belonging to the installation before replacing
+it, then start each with the upgraded binary. For an independently installed
+candidate, its `stop` command can stop the older observer in the same explicitly
+selected owned state. Do not run `remove-state`; receipts need not be deleted.
+
+Restart preserves historical receipts and reconciles inputs. It does not promise
+CURRENT: a newer failure, unstable execution, incomplete contract, changed input,
+or observation uncertainty remains visible under the normal rules.

package/docs/user/shell.md

@@ -0,0 +1,25 @@
+# Shell usage
+
+Run `redue start` once for the project/configuration you want to observe. A shell,
+terminal multiplexer, and agent using that same config share its backend. Closing
+the terminal does not stop the observer. `redue stop` does.
+
+`redue status --short` is the intended small indicator:
+
+```text
+REDUE UNVERIFIED
+```
+
+It reads the cached snapshot, checks its expiry and observer liveness, and never
+synchronizes, traverses installed packages, or runs probes/checks. Like ordinary
+status, it can remain conservative when caller context or installed hardlinks
+need a synchronized read. Do not turn that uncertainty into a green badge.
+
+For an existing async/bounded prompt framework, use `redue status --short` from
+the project root as the segment command and display unavailable on errors or
+timeout. Node startup and configuration parsing still have a cost. REDUE does
+not install a shell hook, edit global shell files, or provide its own prompt
+scheduler. Running it manually is supported in PowerShell and POSIX shells.
+
+Never put `status --sync` or `explain` in a prompt. Use those deliberately when
+you need a decision and synchronization is worth its cost.

package/docs/user/supported-projects.md

@@ -0,0 +1,89 @@
+# Supported Node projects
+
+`init` detects npm from `package-lock.json`/`npm-shrinkwrap.json` or an npm
+`packageManager` declaration. It detects Yarn from `yarn.lock` or its
+declaration and reads `.yarnrc.yml` to distinguish node-modules/classic from
+PnP and other modes. A Yarn v1 lockfile can identify the classic layout, but
+without a declared Yarn version `init` does not create a runnable config:
+Corepack can select a different version and edit `package.json`. Conflicting
+package managers are reported without pretending that installation coverage
+is known. When npm is not pinned in `package.json`,
+`init` reads the local npm executable's package manifest if available; it
+leaves the version unknown rather than guessing if that inspection fails.
+
+At the repository root, `init` looks for existing typecheck, test, lint, and
+build scripts. It prefers familiar script names, then unique recognizable
+`tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
+matches are reported as ambiguous rather than guessed. It never creates a new
+project script. It recognizes canonical
+`tsc --noEmit` on local npm installations as a candidate for automatic
+qualification. Before CURRENT is possible, a read-only probe checks the
+TypeScript configuration and effective file list, local compiler, installed
+contents, npm/Node identity, and relevant caller context. Unsupported plugins,
+preloads, config graphs, or outside-root inputs leave the check UNVERIFIED with
+an explanation. A discovered script can still be run and recorded in that
+state. Root and package-level npm/Yarn workspace scripts are discovered from
+`package.json` workspace declarations. Pinned Yarn 4 `node-modules`/classic
+workspaces with a standalone `tsc -p .` script, local TypeScript, a conventional
+`src` include, and Node module resolution can qualify automatically. For one
+workspace, use `redue init --workspace NAME --check typecheck`; it writes only
+that check and keeps derived relationships out of project configuration. The
+contract observes selected `src` membership, root/package TypeScript config,
+built declarations of internal workspace dependencies, and physical installed
+files. It rechecks TypeScript's effective input list with a read-only probe.
+A sibling workspace is not an input merely because it shares the repository.
+When an internal dependency is consumed through built declarations, changing
+only its source does not stale the selected check until the consumed output
+changes. Unsupported custom resolution, project references, outside-root
+source links, and installation modes remain recording-only. Other Yarn
+typechecks, Vitest/Jest, ESLint, and builds start recording-only unless a
+separately justified explicit contract is provided.
+In particular, test caches and build-generated inputs are not excluded to
+make evidence green.
+
+Pinned pnpm 12 projects are read from `packageManager`, `pnpm-workspace.yaml`,
+the lockfile, and the installed `node_modules/.modules.yaml` metadata. The
+supported local layouts are pnpm's standard isolated and hoisted
+`node_modules` with a project-local `.pnpm` virtual store. `init` can discover
+root and workspace scripts. For a standalone `tsc --noEmit` or `tsc -p ...`
+script in the narrow TypeScript contract, it records the exact installed
+compiler invocation directly. This avoids pnpm 12's task-run bookkeeping
+writes during `pnpm run`; it does not alter the project's script. Test, lint,
+build, and ambiguous TypeScript scripts still execute through `pnpm run` and
+start recording-only. The generated `@typescript-bin:WORKSPACE` token resolves
+the local compiler when the check runs; it is not an absolute machine path.
+
+The pnpm contract indexes consumed installed package contents inside the
+project, selected workspace source, linked workspace declaration outputs,
+relevant manifests, configuration, and installation metadata. The global pnpm
+store is neither watched nor deleted. PnP, custom modules/virtual-store roots,
+global virtual stores, injected workspace dependencies, and external links
+without an observed boundary remain recording-only with a reason. Installed
+files with hard-linked aliases outside the checkout remain recording-only on
+macOS: writes through an unseen alias cannot support CURRENT there. On Linux,
+redue watches project-installed file inodes and rehashes the selected
+installed inputs on every synchronized read. A cached read remains UNVERIFIED
+for these pnpm checks; a synchronized read can establish CURRENT after the
+rehash. If an inode watch cannot be installed, observation becomes unavailable
+instead of dropping that file. The global store is not watched. An absent
+optional package remains unqualified when Node could later
+resolve it from an unobserved ancestor `node_modules`; project-local candidate
+locations are still tracked for plan changes. No configuration assertion is
+generated to hide either gap.
+
+An unobservable source symlink or missing Git checkout is reported by `init`
+before writing a config. A local explicit configuration can grant a narrow
+external observation root after review; `init` will not add machine-specific
+paths to a project config automatically.
+
+The generated config is project-relative and versioned. Runtime state and
+receipts live separately. `packageManager`, `checks[].script`, `kind`,
+`inputs`, optional `workspace`, and optional `qualification` are the generated
+public fields. The
+CLI also accepts `checks[].command` as exact argv for arbitrary checks;
+`@node`, `@project`, `@which:NAME`, and the narrow
+`@typescript-bin:WORKSPACE` token are resolved at invocation. A command
+or input-declaration change invalidates previous evidence.
+
+
+Windows supports the same qualified contracts on local NTFS, with project-visible installed hardlinks revalidated during synchronized reads. Cached hardlink-sensitive applicability is conservative. No package-manager or platform promises that synchronization is cheaper than execution.

package/examples/redue.config.json

@@ -0,0 +1,8 @@
+{
+  "schema": 1,
+  "checks": [{
+    "name": "migration",
+    "command": ["@node", "tools/check-migrations.mjs"],
+    "inputs": ["migrations/**", "tools/check-migrations.mjs"]
+  }]
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@redue/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "private": false,
+  "version": "0.1.0-alpha.3",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "type": "module",
+  "bin": {
+    "redue": "./bin/redue.mjs"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
+    "test:package": "node test/acceptance/package-smoke.mjs",
+    "demo": "node test/acceptance/package-smoke.mjs --demo"
+  },
+  "dependencies": {
+    "@parcel/watcher": "2.5.6",
+    "picomatch": "2.3.2",
+    "yaml": "2.8.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "typescript": "5.6.3"
+  },
+  "description": "Persistent verification state for developers and coding agents.",
+  "homepage": "https://github.com/msiric/redue",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msiric/redue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/msiric/redue/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "docs/user/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "license": "Apache-2.0"
+}

package/src/cached-state.mjs

@@ -0,0 +1,42 @@
+// The same fail-conservative cached reader serves the CLI and execution layer.
+import fs from 'node:fs';
+import path from 'node:path';
+import {processAlive} from './process-liveness.mjs';
+import {readReceipts,readReceiptSnapshot,receiptRevision} from './state-store.mjs';
+const unknown=(reason,checks)=>({schema:1,state:'unverified',current:0,stale:0,failed:0,observed_failed:0,
+  unverified:checks.length,
+  checks:checks.map(c=>({name:c.name,result:null,freshness:'UNVERIFIED',reason,
+    invocation:null,changed_inputs:[],reuse_eligible:false})),
+  observation:{healthy:false,reason}});
+export function unavailableCached(state,reason,checks=[]) {
+  let value;try{value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));}
+  catch{value=unknown(reason,checks);}
+  if(!value||!Array.isArray(value.checks))value=unknown(reason,checks);
+  let receipts=null,revision=null;
+  try{const snapshot=readReceiptSnapshot(state);receipts=snapshot.value.checks;revision=snapshot.revision;}
+  catch(error){reason+=`; latest receipt unavailable; prior outcome only: ${error.message}`;
+    try{receipts=readReceipts(state).checks;}catch{/* retain cached historical rows */}}
+  const rows=(value.checks||[]).map(row=>{
+    const latest=receipts?.[row.name];
+    return {...row,...(receipts?{result:latest?.result||null,invocation:latest?.invocation||null,
+      target_provenance:latest?.target||null,coverage_at_run:latest?.coverage||null}:{}),
+      freshness:'UNVERIFIED',reason,reuse_eligible:false,declared_inputs_match:null};
+  });
+  return {...value,receipt_revision:revision,state:'unverified',current:0,stale:0,failed:0,
+    observed_failed:rows.filter(row=>row.result==='FAIL').length,
+    unverified:Math.max(1,rows.length),checks:rows,
+    observation:{...value.observation,healthy:false,reason}};
+}
+export function readCachedStatus(state,checks=[]) {
+  try{const value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));
+    if(typeof value.receipt_revision!=='string')
+      return unavailableCached(state,'receipt selection is unconfirmed; synchronize status or restart an older observer',checks);
+    if(value.receipt_revision!==receiptRevision(state))
+      return unavailableCached(state,'receipt selection changed; synchronize status to evaluate the latest outcome',checks);
+    if(Date.now()>=value.updated_at&&Date.now()<=value.expires_at&&
+      value.expires_at-value.updated_at<=3000){
+      if(processAlive(value.pid))return value;
+      return unavailableCached(state,'observer process unavailable',checks);}
+  }catch{}
+  return unavailableCached(state,'observer heartbeat expired or unavailable',checks);
+}