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

package/bin/vstate.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Compatibility entry point for local pre-release workflows.
+import './redue.mjs';

package/docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+For users:
+
+- [Install, initialize, run, and remove](user/getting-started.md)
+- [Supported projects and conservative boundaries](user/supported-projects.md)
+- [Configuration](user/configuration.md)
+- [Coding-agent decision policy](user/agents.md)
+- [JSON contract](user/json.md)
+- [Shell usage](user/shell.md)
+
+For contributors:
+
+- [Architecture](contributor/architecture.md)
+- [Observation and recovery](contributor/observation-recovery.md)
+- [Reproducible terminal demo](contributor/demo.md)
+- [Release procedure](contributor/releasing.md)
+
+[Historical acceptance evidence](acceptance/README.md) is retained separately.
+It records measured environments and limitations; it is not the getting-started guide.

package/docs/user/agents.md

@@ -0,0 +1,32 @@
+# Agent decision policy
+
+Use the CLI; no SDK or bespoke agent integration is required. Add these
+instructions to a session or project only with its owner's permission.
+
+1. Query ordinary `redue status --json` first.
+2. If a check has `freshness: "CURRENT"`, `result: "PASS"`, and
+   `reuse_eligible: true`, reuse it. Do not rerun merely for freshness.
+3. If STALE, run `redue run CHECK` when that verification is needed.
+4. If the historical `result` is FAIL, report it honestly. The human CLI calls
+   this FAILED; applicability is a separate field, never an excuse to call it green.
+5. If UNVERIFIED, inspect its reason. Use `status --sync --json` when establishing
+   applicability is worthwhile, or rerun the underlying check when cheaper/simpler.
+   Use `redue run CHECK` if a new receipt is wanted. Incomplete coverage can remain
+   UNVERIFIED even after success.
+6. Do not assume synchronization is cheaper than execution. There are no universal
+   package-manager or OS thresholds. Inexpensive checks may be cheaper to rerun.
+
+`redue explain CHECK --json` gives synchronized detail, including a known changed
+input when available. It has the same cost caveat as synchronized status.
+
+No previous conversation history is needed to read a persisted receipt. Still
+consider independent task-specific reasons to run verification: the configured
+check is not universal product correctness. Report additional uncaptured checks
+separately. Do not infer that an outer invocation's success proves a specific
+check ran or that an upstream cache was hit; inspect `target_provenance`.
+
+On a CLI error, unhealthy observation, or unavailable context, do not infer
+CURRENT. Do not delete state or reset receipts to make the output green.
+
+REDUE tells you what evidence exists and whether it still applies. It does not
+promise that establishing applicability is cheaper than every possible check.

package/docs/user/configuration.md

@@ -0,0 +1,57 @@
+# Configuration
+
+Prefer `redue init` over hand-authoring a qualified contract. A typical generated
+npm configuration is concise and portable:
+
+```json
+{
+  "schema": 1,
+  "root": ".",
+  "packageManager": "npm",
+  "checks": [{
+    "name": "typecheck",
+    "script": "typecheck",
+    "kind": "typecheck",
+    "qualification": "typescript-noemit-v1",
+    "inputs": ["package.json", "package-lock.json", "tsconfig*.json", "src/**"]
+  }]
+}
+```
+
+The exact inputs are derived from the detected project; use the emitted config,
+not this example to assert your project's coverage. Generated Yarn/pnpm workspace
+checks also identify the owning workspace and actual command. Large dependency
+relationships stay in local runtime state. `qualification` selects a supported
+validation recipe; it is not a blanket coverage assertion.
+
+Use `--config FILE` to select an external configuration. `root` is relative to
+that file. Runtime paths, resolved executables, local evidence, and sockets stay
+out of version-controlled configuration.
+
+## Arbitrary commands
+
+An unrecognized ecosystem can still record ordinary execution:
+
+```json
+{
+  "schema": 1,
+  "checks": [{
+    "name": "migration",
+    "command": ["@node", "tools/check-migrations.mjs"],
+    "inputs": ["migrations/**", "tools/check-migrations.mjs"]
+  }]
+}
+```
+
+Commands are exact argv, not shell text. Use `cwd` for a project-relative working
+directory. `@node`, `@project`, and `@which:NAME` resolve explicit invocation facts.
+Manual checks start recording-only: a plausible list of files is not proof of a
+complete input boundary. Do not copy coverage assertions from unrelated projects.
+
+Advanced explicit contracts may declare `generatedInputs`, `installedInputs`, narrow
+`allowedExternalRoots`, read-only `probes`, and relevant `environment`. These are
+reviewed escape hatches, not onboarding requirements. A coverage rationale cannot
+override unsupported storage, unresolved links, missing inputs, or observation failure.
+
+Changing commands, relevant configuration, installed material, or consumed inputs
+invalidates prior applicability. It does not erase historical execution outcomes.

package/docs/user/getting-started.md

@@ -0,0 +1,127 @@
+# Install and use REDUE
+
+Requirements: Git; Node 22 or newer with npm; an existing local JS/TS checkout
+with its dependencies installed. Linux additionally needs `python3`. Supported
+storage is local APFS on macOS, NTFS on Windows, and the documented native Linux
+filesystems. Network/FUSE/overlay mounts are not qualified Linux storage.
+Node 22 and 24 are the release-test matrix; newer majors are not yet acceptance claims.
+
+Install the public alpha:
+
+```sh
+npm install --global @redue/cli@alpha
+redue --version
+```
+
+For an unpublished source candidate, run `npm ci` and `npm pack --json`, then
+install the exact filename reported by npm with `npm install --global ./<filename>`.
+
+These commands also work in PowerShell (use `npm.cmd`/`redue.cmd` when a local
+PowerShell script policy blocks generated `.ps1` shims; do not change policy).
+No build step, custom installer, account, or login service is required. Installing
+npm dependencies uses the registry; normal local observation does not require network.
+
+For a reversible user-owned prefix, POSIX shells:
+
+```sh
+npm install --global --prefix "$HOME/.local/redue-alpha" @redue/cli@alpha
+export PATH="$HOME/.local/redue-alpha/bin:$PATH"
+```
+
+PowerShell:
+
+```powershell
+$reduePrefix = Join-Path $env:LOCALAPPDATA 'redue-alpha-install'
+npm.cmd install --global --prefix $reduePrefix @redue/cli@alpha
+$env:PATH = "$reduePrefix;$env:PATH"
+redue.cmd --help
+```
+
+These PATH changes affect only the current shell. Alternatively invoke the
+installed entry point directly: POSIX `node "$HOME/.local/redue-alpha/lib/node_modules/@redue/cli/bin/redue.mjs"`;
+Windows `node "$reduePrefix/node_modules/@redue/cli/bin/redue.mjs"`.
+
+## Moving from alpha.1
+
+If the personal-scope alpha.1 package is installed, stop the project's observer
+and replace that package before installing the canonical command:
+
+```sh
+redue stop
+npm uninstall --global @msiric/redue
+npm install --global @redue/cli@alpha
+```
+
+Use the same `--prefix` on both npm commands if your installation has a custom
+prefix. Uninstalling the package does not remove local verification evidence;
+`redue remove-state` is a separate, explicit action. Alpha.1 remains available as
+historical software and is superseded for package identity, not a runtime defect.
+
+## First project
+
+From the project root:
+
+```sh
+redue init --dry-run
+redue init
+redue start
+redue run typecheck
+redue status
+redue explain typecheck
+```
+
+Use a check actually printed by `init`. For a workspace:
+`redue init --workspace @example/package --check typecheck`.
+Initialization previews detected commands and qualification confidence before writing
+`redue.config.json`. An existing config is never overwritten. No checks are run and
+no dependencies installed. A missing/unsupported boundary is explained.
+
+“Ready to qualify” means REDUE has a supported recipe whose prerequisites will be
+validated. It is not a receipt. “Recording-only” can record PASS/FAIL without claiming
+reusability. Qualification can change when configuration or installation changes.
+
+`run` streams normal output and preserves execution environment and cancellation.
+For the narrow pnpm TypeScript contract, `init` explicitly shows the direct installed
+compiler invocation it selects; other scripts run through the package manager.
+Only use configs and probes from trusted repositories: these execute local code.
+
+`status` is cached and conservative. `status --sync` and `explain` revalidate caller
+context and may execute read-only probes. Synchronization can be slower than a cheap
+check, especially on Windows. Choose deliberately. A timeout is UNVERIFIED, not green.
+
+## Lifecycle and removal
+
+`start` starts this config's owned observer, or reports that it is already running.
+If already running, use `status`; do not create a second state directory just to
+start another observer. Startup may report initialization before inputs are ready.
+`stop` stops that observer and retains historical evidence. After restart, observation
+is reconciled before reuse.
+
+```sh
+redue stop
+redue start
+redue remove-state
+npm uninstall --global @redue/cli
+```
+
+For an isolated installation, use the same `--prefix` on uninstall. Remove state
+**before** uninstalling the command. No broad recursive deletion command is needed.
+`remove-state` checks its ownership marker and stops only that observer. It does not
+remove project files, dependencies, another tool's watches, or other REDUE configurations.
+To remove project configuration, inspect and delete `redue.config.json` yourself.
+
+Runtime state is separate from durable project config. Legacy directory spelling is
+retained for compatibility, not copied into your config:
+
+| OS | Default state base |
+| --- | --- |
+| macOS | `~/Library/Application Support/vstate/` |
+| Linux | `$XDG_STATE_HOME/vstate/`, otherwise `~/.local/state/vstate/` |
+| Windows | `%LOCALAPPDATA%/vstate/` |
+
+A checkout/config identity selects a dedicated child directory. Use
+`--state-dir /your/owned/redue-project-state` to choose a dedicated directory outside
+all observed roots; its basename must start with `redue-` or legacy `vstate-`.
+For a removed checkout, `redue --state-dir /your/owned/redue-project-state remove-state`
+still works without rebuilding its compiler/configuration. Ownership/active-run conflicts
+are actionable errors, never resolved merely by deleting an old lock.

package/docs/user/json.md

@@ -0,0 +1,59 @@
+# Alpha JSON interface (schema 1)
+
+Use `status --json` for cached state, `status --sync --json` for caller-aware
+applicability, and `explain CHECK --json` for selected synchronized detail.
+`detail` remains an alias. Successful reads emit one JSON object, no human prose.
+
+```json
+{
+  "schema": 1,
+  "state": "stale",
+  "current": 0, "stale": 1, "failed": 0, "observed_failed": 0, "unverified": 0,
+  "checks": [{
+    "name": "typecheck",
+    "result": "PASS",
+    "freshness": "STALE",
+    "reason": "src/main.ts changed",
+    "changed_inputs": ["src/main.ts"],
+    "reuse_eligible": false,
+    "invocation": {"runId": "opaque-run-id", "status": "exited", "exitCode": 0, "durationMs": 940}
+  }],
+  "observation": {"healthy": true}
+}
+```
+
+Stable-enough-for-alpha fields:
+
+| Field | Contract |
+| --- | --- |
+| `checks[].name` | Configured check identity. |
+| `result` | Historical `PASS`, `FAIL`, or null. A failed invocation is not green even with CURRENT applicability. |
+| `freshness` | `CURRENT`, `STALE`, or `UNVERIFIED`, independent of result. |
+| `reuse_eligible` | True only for qualified, applicable passing evidence. Never derive permission to reuse from outcome alone. Missing means false. |
+| `reason` | Human explanation; not a stable machine enum. Do not parse it to authorize reuse. |
+| `changed_inputs` | Known changed relevant paths when available, possibly only the first difference; empty/missing is not proof of no changes. |
+| `invocation` | Null without a receipt; otherwise run ID, completion `status`, duration, exit code/signal when known. Status distinguishes exited, interrupted, and start/capture failure. |
+| `target_provenance` | Available target evidence. Unknown is not executed or cache-hit. |
+| `observation.healthy` | False means no check is reusable. Additional reason/phase diagnostics may appear. |
+| `state` | Aggregate lowercase current/stale/failed/unverified (and runtime pending states where applicable). Use per-check fields for decisions. |
+
+Counts cover the whole configuration even when `explain CHECK` filters `checks`.
+`failed` counts applicable failures; `observed_failed` preserves historical failures
+regardless of applicability. Fields not listed here are diagnostic and may evolve.
+Ignore unknown fields; reject unknown schema versions. These responses contain local
+paths/check names and must not be uploaded automatically.
+
+`init --json` returns discovery levels (`ready`, `recording`, `unsupported`),
+reasons, workspace ownership, `written`, and `proposed_config`. Ready is not PASS.
+`init --dry-run --json` writes no config and runs no check.
+
+Read commands normally exit 0 even when the evidence is not current. Errors exit
+nonzero; synchronized transport failures may still return conservative JSON.
+Usage/configuration errors go to stderr and are not guaranteed JSON. Never treat
+a failed read as authority from a previously cached answer.
+
+`run CHECK --json` preserves ordinary command stdin/stdout/stderr and appends a
+JSON summary. **Its stdout is not a JSON-only stream.** Query status/details after
+completion for machine-readable evidence. Normal check exit codes are preserved;
+interruption/process-start failures are nonzero. REDUE retains metadata and receipts,
+not arbitrary terminal output. The CLI does not infer tests executed from prose.

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.2",
+  "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,27 @@
+// 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';
+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=[]) {
+  try {const value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));
+    const checks=(value.checks||[]).map(row=>({...row,freshness:'UNVERIFIED',
+      reason,reuse_eligible:false,declared_inputs_match:null}));
+    return {...value,state:'unverified',current:0,stale:0,failed:0,
+      unverified:Math.max(1,checks.length),checks,
+      observation:{...value.observation,healthy:false,reason}};
+  }catch{return unknown(reason,checks);}
+}
+export function readCachedStatus(state,checks=[]) {
+  try{const value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));
+    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);
+}