diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6b474e7..ba734ac 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,6 +39,8 @@ jobs: run: npm ci --ignore-scripts - name: Build run: npm run build + - name: Typecheck and Markdown link check + run: npm run lint - name: Core, CLI and fresh MCP regression suite run: npm test - name: Standalone installation and failure-path checks diff --git a/.gitignore b/.gitignore index 06807f3..6acb87a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,10 @@ scratch /MOZAK.json /MOZAK.md /.mozak-write-lock +# Old generated demos with the uppercase name. scripts/record-demo-video.mjs and +# scripts/record-agent-chat-video.mjs write them; regenerate them before scripts/package-demo-kit.mjs. +# The README demo lives on the readme-assets release instead. +/docs/assets/mozak-demo.gif +/docs/assets/mozak-demo.mp4 +/docs/assets/mozak-agent-chat.gif +/docs/assets/mozak-agent-chat.mp4 diff --git a/CHANGELOG.md b/CHANGELOG.md index ae05a20..17d9c8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,23 +4,42 @@ User-visible changes, newest first. Releases are git tags `vX.Y.Z` on `main`; `m ## Unreleased -## 0.4.8 (not yet tagged) +## 0.5.0 (not yet tagged) + +0.5.0 includes the fixes prepared as 0.4.8, which was never tagged. + +**Upgrade every machine before you star a plan.** mozak before 0.5.0 refuses an inventory that has a `focus` list (`unknown key "focus"`). + +### Added +- **Focus tab.** The Obsidian sidebar tabs are Open, Focus and Done; the All tab is gone and rejected plans show in no tab (`mozak plans --include-rejected` still lists them). A star on every plan row adds the plan to the scope's `focus` list in `mozak-inventory.json` or takes it out. The sidebar opens on Focus when it has plans, else Open, and remembers the last tab. `mozak focus list [--scope ID]` reads the lists, `mozak focus add|remove --scope ID --plan ID` (owner) changes them, and MCP has a read-only `mozak_focus`. Focus is a sidebar marker only: it is not plan state, `mozak.json` and `mozak.md` never change, and agents cannot write it. A starred id that is no longer a plan is a `check` warning (`focus-unknown-plan`). See [docs/installation.md](docs/installation.md#6a-focus-list). +- **Owner annotations, off by default.** Cross-plan refs (needs, informs, supersedes) and deadlines in a `mozak.annotations.json` sidecar, written only through the owner route `mozak annotate`, read by `mozak graph`, `mozak ready`, `mozak plans --sort deadline` (MCP `mozak_plan_graph`, `mozak_ready`) and the sidebar. Turn them on per scope with `scopes..annotations: true` in the `mozak-settings.json` next to the inventory. A scope without it behaves like 0.4.7: the sidecar is never read and `mozak.md` does not change. See [docs/annotations.md](docs/annotations.md). +- **Plans index, locators and similar plans.** `mozak plans-md` (owner) writes a `plans.md` with plan titles and states at each notes repo root. `mozak locators` shows where each source and evidence locator points. `check` lists cited notes that changed after they were cited. `mozak similar` (MCP `mozak_similar`) reports duplicate, overlapping and superseding plans across scopes. See [docs/plans-index.md](docs/plans-index.md). +- **Store hygiene.** The lock owner record names its host, and the owner route `mozak recover` clears a write lock left by another host or a dead local process (`check` reports `write-lock-stuck`). `mozak plan prune --rejected` (owner) removes listed rejected plans; refs to them resolve as pruned and the id cannot be proposed again. `mozak check --history N` reports hand edits to `mozak.json`. `mozak sync --local` fast-forwards git repos that hold local scopes, under the scope locks, and never pushes; the sidebar sync button does the same. +- **Experimental read-set rebase, off by default.** With `concurrency.rebase: true` in `mozak-settings.json` (top level or per scope), a stale `observe`, `save-discussion` or new-id `propose` commits onto the fresh state when nothing it read has changed. Decisions, `revise`, `complete` and `attach-spec` keep the exact snapshot check. +- **Counts-only usage log, opt-in.** With `MOZAK_USAGE_LOG=on` or `"usageLog": true` in `mozak-settings.json`, each call appends one line of counts and codes (never plan text) to `.mozak-cache/usage/` next to the inventory. Off by default. +- `npm run typecheck`, `npm run lint` (typecheck plus a relative-link check, also run in CI) and `npm run loc`. `scripts/readme-example.mjs` reproduces the README example on a throwaway scope. ### Fixed -- `propose` refuses an exact copy of a non-completed plan as `duplicate-plan-candidate` even when the plan ids carry different numbers. Before, such a copy was let through. -- A merge whose combined discussion would exceed 32 questions is refused as `merge-capacity` at propose and at approval. Before, the extra questions were silently cut. -- Writes hash `mozak.json` and `mozak.md` again right before each rename and stop with `graph-changed-during-write` when another editor changed them, keeping that edit. This covers `plan delete` too. It narrows the race with editors that ignore the write lock, it does not close it. +- `propose` refuses an exact copy of a non-completed plan as `duplicate-plan-candidate` even when the plan ids carry different numbers. +- A merge whose combined discussion would exceed 32 questions is refused as `merge-capacity` at propose and at approval, instead of silently cutting questions. +- Writes hash `mozak.json` and `mozak.md` again right before each rename and stop with `graph-changed-during-write` when another editor changed them (also for `plan delete`). It narrows the race with editors that ignore the write lock, it does not close it. - `init` and projection repair add ignore lines for the write lock and temp files, and `check` reports `lock-not-ignored` and `lock-in-git`. -- A late supporting observation no longer drops an owner-accepted outcome from `done` to `evidence` in the roadmap, `mozak.md` and `needs` checks. Only a new challenge reopens it. `plan complete` still needs an owner acceptance bound to the exact current evidence. +- A late supporting observation no longer drops an owner-accepted outcome from `done` to `evidence`. Only a new challenge reopens it. `plan complete` still needs an owner acceptance bound to the exact current evidence. +- A `mozak.md` that differs only by CRLF line endings or trailing whitespace counts as current. - The Obsidian plugin opens plans inside a vault that was opened through a symlink. -- The test suite passes with the default macOS `TMPDIR` and with `TMPDIR=/tmp` (scratch paths behind a symlink). +- The test suite passes with the default macOS `TMPDIR` and with `TMPDIR=/tmp`. ### Changed -- An inventory may carry a reserved `x` object at the top or in a scope entry. This client ignores it and `check` reports `inventory-x-ignored`, so a future setting does not break older clients. -- A failed MCP tool call now starts with a one-line `reason` and the `issues`, before the rest of the result. A failed `observe` echoes its `unsavedRequest` last, in the CLI JSON too. Hosts that cut long tool output still show why the call failed. +- Removed the unused format-1 modules from `@mozak/core` (`parse`, `check`, `graph`, `stale`, `translate`, `init`, `write`, `plan`) and their exports. No CLI, MCP or plugin route used them, and format-1 routes still refuse with `unsupported-legacy-operation`. See [docs/audit-2026-10.md](docs/audit-2026-10.md). +- Common error messages end with the next step (`stale-input`, `scope-not-found`, `plan-not-found`, `operation-conflict`, `busy` and others). Codes and exit codes are unchanged. +- A failed MCP tool call starts with a one-line `reason` and the `issues`, before the rest of the result. +- Local and vault-plans scope reads never fetch. Remote reads mark `remoteFreshness` and skip the network for 10 minutes after a failed fetch. +- An inventory may carry a reserved `x` object at the top or in a scope entry. This client ignores it and `check` reports `inventory-x-ignored`. +- The compiler runs with `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch` and `noImplicitOverride`. ### Docs -- README: new "Reads and the network" section on what reads of a repo-mode GitHub scope may fetch, cache and push, and the background release check. +- README rewritten around the problem mozak solves, with a real example and the install line. New section "Reads and the network". +- The plugin README and disclosures say what the plugin writes: a stale `mozak.md` it regenerates, and the `focus` lists through the star. It never writes plan state. - The installed skill no longer names one host's scheduler, and its examples say "the owner". ## 0.4.7 (2026-10-29) diff --git a/README.md b/README.md index 7aa8565..e13142e 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,54 @@ You work in ideas and plans, not code. Several agents share one plan without ove [![Node 24.11+](https://img.shields.io/badge/node-24.11%2B-339933?style=flat-square)](docs/installation.md) [![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS-blue?style=flat-square)](docs/installation.md) -[What it is](#what-it-is) · [See it run](#see-it-run) · [Install](#install) · [How it works](#how-it-works) · [Obsidian](#see-everything-in-obsidian) · [Safety](#safety) · [Tested](#what-is-tested-and-what-is-not) · [Docs](docs/installation.md) +[What it is](#the-problem) · [Example](#a-short-example) · [See it run](#see-it-run) · [Install](#install) · [How it works](#how-it-works) · [Obsidian](#see-everything-in-obsidian) · [Safety](#safety) · [Tested](#what-is-tested-and-what-is-not) · [Docs](docs/installation.md) --- +## The problem + +Coding agents forget the plan between sessions, so you explain the project again. When several agents work at once, one can overwrite what another just wrote. And an agent can start building before you agreed on what to build. + +mozak fixes this with plain files: + +- **Every agent reads the same plan.** `mozak.json` holds it and `mozak.md` is a readable copy. You never explain the project twice. +- **Agents propose, you decide.** Agreeing on *what* to do and agreeing to *start building* are two separate yeses. +- **Stale writes are refused.** An agent that writes from an old copy gets `stale-input` and must reread. Nothing is overwritten. +- **One view across all your projects.** The Obsidian plugin shows every project's plans and progress in one sidebar, with a Focus tab for the plans you starred. + +No cloud, no account, no background service. + +```bash +npm install -g mozak && mozak doctor --fix +``` + +## A short example + +Two agents read the same plan, then both propose at once. The first write lands. The second is refused because its copy is now old, so it cannot overwrite the first. This is real output: `node scripts/readme-example.mjs` reproduces it on a throwaway scope after `npm run build`. + +```text +$ mozak plan propose --scope my-app --request a.json # agent A proposes +status: ok +committed: true +(exit 0) + +$ mozak plan propose --scope my-app --request b.json # agent B proposes from the same, now old, snapshot +status: stale-input +committed: false +stale-input: snapshot changed; reread before submitting a new operation: take the new snapshot from context as expected and use a new operationId +(exit 3) + +$ mozak plans --scope my-app # what is in the plan now +awaiting (1) + - Add dark mode [dark-mode] + review: direction approval + outcome: The app has a dark theme +``` + +The plan is now waiting for your yes. Agent B rereads and proposes again from the new snapshot. + ## See it run
@@ -123,7 +165,7 @@ A project with `root` is a local folder. A project with `remote` is a GitHub rep ## See everything in Obsidian -The Obsidian plugin in [`packages/obsidian`](packages/obsidian) shows every project from your inventory in the sidebar, notes and GitHub repos alike. Filter by **All**, **Open** or **Done**. Open plans show a small progress strip, one segment per outcome. Click a plan to open its section in the scope's `mozak.md`, which reads like a note: purpose, a roadmap of the outcomes with the current stop, a status table and the full plan text. The sidebar is for reading and navigating. You approve plans in your agent chat, not in Obsidian. The plugin never approves or changes a plan. It may regenerate a stale `mozak.md`, the same as `mozak render`. +The Obsidian plugin in [`packages/obsidian`](packages/obsidian) shows every project from your inventory in the sidebar, notes and GitHub repos alike. Tabs: **Open**, **Focus** (plans you starred) and **Done**. Open plans show a small progress strip, one segment per outcome. Click a plan to open its section in the scope's `mozak.md`, which reads like a note: purpose, a roadmap of the outcomes with the current stop, a status table and the full plan text. The sidebar is for reading and navigating. You approve plans in your agent chat, not in Obsidian. The plugin never approves or changes a plan and never writes plan state. It may regenerate a stale `mozak.md`, the same as `mozak render`, and the star on a plan row edits that scope's `focus` list in `mozak-inventory.json` (the same as `mozak focus add|remove`). Install it from Obsidian: **Settings, Community plugins, Browse**, search for **mozak**, then Install and Enable ([directory page](https://community.obsidian.md/plugins/mozak)). From a source checkout you can also run: @@ -133,7 +175,7 @@ node scripts/install-obsidian-plugin.mjs /path/to/your/vault --build The plugin finds `mozak-inventory.json` by searching upward from the vault folder, or you can set its path in the plugin settings. Each GitHub project shows a globe or lock badge for a public or private repo. -**Plugin disclosures (desktop-only, `isDesktopOnly: true`):** When your `mozak-inventory.json` lists scopes outside the current vault, the plugin reads their `mozak.json`, `mozak.md`, `README.md` and `AGENTS.md` files from those configured paths and watches them when **Auto-refresh** is enabled. It never scans folders not listed in your inventory and never approves or changes a plan (it may regenerate a stale `mozak.md` projection when there are no unmerged hand edits). For remote GitHub scopes (`"remote": "github:owner/repo"` without vault-hosted `"plans"`), clicking **Sync remote scopes** or enabling **Repo sync interval (seconds)** runs your local `git` with your existing git login on the hidden `.mozak-cache` copy: `git fetch`, then a reset of that copy to the fetched commit. If an earlier mozak write left a plan commit unpushed (for example after a network failure), the sync first commits and pushes that pending `mozak.json` / `mozak.md` change. Set the sync interval to `0` to turn background git activity off. The sync also asks the public GitHub API, without a login and at most once a day per repo, whether each remote repo is public. The update notice only reads a cache file the CLI writes. The plugin never installs or updates itself, and has no telemetry. See [`packages/obsidian/README.md`](packages/obsidian/README.md#disclosures-obsidian-community-plugin-policy) for the full disclosure list. +**Plugin disclosures (desktop-only, `isDesktopOnly: true`):** When your `mozak-inventory.json` lists scopes outside the current vault, the plugin reads their `mozak.json`, `mozak.md`, `mozak.annotations.json` (when present and annotations are on for that scope), `README.md` and `AGENTS.md` files from those configured paths and watches them when **Auto-refresh** is enabled. It never scans folders not listed in your inventory and never approves or changes a plan (it may regenerate a stale `mozak.md` projection when there are no unmerged hand edits, and the star toggle edits the `focus` lists in `mozak-inventory.json`). For remote GitHub scopes (`"remote": "github:owner/repo"` without vault-hosted `"plans"`), clicking **Sync vaults and repos** or enabling **Repo sync interval (seconds)** runs your local `git` with your existing git login on the hidden `.mozak-cache` copy: `git fetch`, then a reset of that copy to the fetched commit. If an earlier mozak write left a plan commit unpushed (for example after a network failure), the sync first commits and pushes that pending `mozak.json` / `mozak.md` change. The button also fast-forwards local vault repositories under scope locks, without pushing or merging diverged histories. That local-vault step is not run by the background timer. Set the sync interval to `0` to turn background git activity off. The sync also asks the public GitHub API, without a login and at most once a day per repo, whether each remote repo is public. The update notice only reads a cache file the CLI writes. The plugin never installs or updates itself, and has no telemetry. See [`packages/obsidian/README.md`](packages/obsidian/README.md#disclosures-obsidian-community-plugin-policy) for the full disclosure list. ## Under the hood @@ -157,6 +199,8 @@ The agent writes plain `mozak.json` and `mozak.md` files in your project folder. | Run the guided planning conversation | the installed skill at `PREFIX/skills/mozak/SKILL.md` | | Rename a project (owner) | `mozak scope retitle` | | Delete plans so they no longer exist (owner) | `mozak plan delete --plans A,B` | +| Star or unstar a plan for the Focus tab (owner) | `mozak focus add\|remove --scope ID --plan ID`, or the star in the sidebar | +| Clear a write lock left by a dead process or another host (owner) | `mozak recover` | | Move pre-0.4 `MOZAK.json` / `MOZAK.md` to lowercase (owner) | `mozak rename-files --all` | Every scope command needs an explicit `--config`. Only the maintenance commands (`upgrade`, `doctor`) run without one. @@ -175,7 +219,7 @@ Local and vault-plans scopes are read from disk. A GitHub scope whose plans live ## What is tested and what is not -**Tested.** 539 unit and integration tests plus 74 installer tests, run in CI on Ubuntu and macOS with Node 24.11 and 26 on every push to `main` and every pull request. They cover: +**Tested.** 630 unit and integration tests plus 74 installer tests, run in CI on Ubuntu and macOS with Node 24.11 and 26 on every push to `main` and every pull request. They cover: - stale writes refused, including two real CLI processes writing at once - a write killed mid-way recovering without losing data @@ -194,6 +238,17 @@ The Obsidian plugin passed Obsidian's automated community review. Its build and - **Real GitHub.** Tests use local bare repos. Real GitHub was checked by hand. - **Unsupported setups.** Windows, network filesystems and diverged remote branches. +## New in 0.5 + +- **Focus tab.** Star a plan in the Obsidian sidebar to put it in Focus. `mozak focus list` shows the stars, and agents can read them but never change them. See [docs/installation.md](docs/installation.md#6a-focus-list). +- **Shorter reads.** `mozak context --brief` gives one short summary per plan, `mozak context --plan ID` the full state of one plan. +- **Owner annotations, off by default.** Links between plans (needs, informs, supersedes) and deadlines, read by `mozak graph`, `mozak ready` and `mozak plans --sort deadline`. Turn them on per scope. See [docs/annotations.md](docs/annotations.md). +- **Plans index and similar plans.** `mozak plans-md`, `mozak locators` and `mozak similar`. See [docs/plans-index.md](docs/plans-index.md). They help you navigate, they make no search-quality claim. +- **Store hygiene.** `mozak recover` clears a stuck write lock, `mozak plan prune --rejected` removes rejected plans, `mozak check --history N` finds hand edits, `mozak sync --local` fast-forwards your vaults. +- **Off unless you turn them on:** the experimental `concurrency.rebase` for parallel agents, and a counts-only usage log (`MOZAK_USAGE_LOG=on` or `"usageLog": true` in `mozak-settings.json`). + +The full list is in [CHANGELOG.md](CHANGELOG.md). + ## Platforms Linux and macOS, Node 24.11 or newer. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c63ba44 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,51 @@ +# mozak docs + +Start with the [README](../README.md). This page lists every doc in the repo and says whether it describes mozak as it is now or records history. + +## Current: how mozak works today + +| Doc | What it covers | +| --- | --- | +| [installation.md](installation.md) | Build from source, the portable installer, `mozak upgrade` and `mozak doctor`, exit codes, recovery, the write lock, the experimental `concurrency.rebase` setting, remote scopes, known limits, and the verification status of every check. | +| [annotations.md](annotations.md) | Owner annotations: cross-plan refs (needs, informs, supersedes), deadlines, `mozak annotate`, `graph`, `ready` and `plans --sort deadline`. | +| [../packages/obsidian/README.md](../packages/obsidian/README.md) | The Obsidian plugin: use, settings, and the community plugin disclosures (files outside the vault, network use, no self-update). | +| [../skills/mozak/SKILL.md](../skills/mozak/SKILL.md) | The agent skill source. It is a template: load the installed copy, not this file. Its `references/` folder has the routes, bootstrap and recovery notes. | +| [brand.md](brand.md) | Name, headline, logo files, colors and fonts. | +| [../CHANGELOG.md](../CHANGELOG.md) | User-visible changes per release. | + +## Launch and release (drafts for the owner) + +| Doc | What it covers | +| --- | --- | +| [release-notes-draft.md](release-notes-draft.md) | DRAFT release notes for the next version. Not published. | +| [obsidian-submission-checklist.md](obsidian-submission-checklist.md) | Each Obsidian community directory requirement, its status in this repo, and what the owner must do to submit. | +| [audit-2026-10.md](audit-2026-10.md) | Code audit of October 2026: removed format-1 code, shared helpers, error messages, compiler flags, dependencies and licenses, open risks. | + +## Design specs for features that shipped + +These explain why a feature works the way it does. The code and [installation.md](installation.md) win where they differ. + +| Doc | What it covers | +| --- | --- | +| [obsidian-roadmap-spec.md](obsidian-roadmap-spec.md) | The readable `mozak.md` with a roadmap, and the plugin as pure navigation. | +| [private-plan-storage-spec.md](private-plan-storage-spec.md) | Plans for public repos kept in a vault folder. | + +## Historical records + +These record how the first packages were specified, built and accepted in October 2026. They are kept for provenance. Do not build against them. Some names in them are older (for example `MOZAK.json`). + +| Doc | What it covers | +| --- | --- | +| [../SPEC.md](../SPEC.md) | Legacy format 1 spec from the first design. Superseded. | +| [detailed-specification-handoff.md](detailed-specification-handoff.md) | Design review and handoff record. | +| [implementation-package-1-plan-state-review.md](implementation-package-1-plan-state-review.md) | Package 1 spec: plan state and review. | +| [implementation-package-1-acceptance.md](implementation-package-1-acceptance.md) | Package 1 acceptance evidence. | +| [implementation-package-2-conversation-and-handoff.md](implementation-package-2-conversation-and-handoff.md) | Package 2 spec: conversation, continuity and implementation handoff. | +| [implementation-package-2-acceptance.md](implementation-package-2-acceptance.md) | Package 2 acceptance and live-trial handoff. | +| [implementation-package-2-live-trial.md](implementation-package-2-live-trial.md) | Package 2 live trial report. | +| [implementation-package-3-portable-workspace.md](implementation-package-3-portable-workspace.md) | Package 3 proposal: official delivery and portable workspace. | +| [assets/src/HANDOFF.md](assets/src/HANDOFF.md), [assets/src/AGENT-CHAT-SCRIPT.md](assets/src/AGENT-CHAT-SCRIPT.md), [assets/brand/BRAND.md](assets/brand/BRAND.md) | Older video and brand briefs from 0.3.0. [brand.md](brand.md) is current. | + +## Checking the docs + +`node scripts/check-links.mjs` checks every relative link and heading anchor in the repo's Markdown files. It exits 1 on a broken link. `npm test` runs the same check. diff --git a/docs/annotations.md b/docs/annotations.md new file mode 100644 index 0000000..6c74a0c --- /dev/null +++ b/docs/annotations.md @@ -0,0 +1,93 @@ +# Cross-plan references and deadlines (owner annotations) + +Plans can point at other plans. A plan can need another plan, inform it, or supersede it. A plan can also have a deadline the owner picked. These facts live in `mozak.annotations.json`, a sidecar next to `mozak.json`. + +## Why a sidecar + +- A change to plan content needs a new direction approval. That clears the spec and the implementation grant. A dependency or a deadline must not cost that. +- A new field in `mozak.json` would need a format bump, and a 0.4.0 client would then refuse the scope. +- The sidecar is invisible to 0.4.0 clients. `mozak.md` stays byte-identical with and without it. +- Agent writes never carry the sidecar hash, so an annotation never makes an agent stale. + +## File format + +```json +{ + "format": "mozak.annotations/v1", + "scopeId": "ID", + "revision": "uuid of the last write", + "updatedAt": "UTC timestamp", + "plans": { + "PLAN": { + "refs": [ + { "id": "ref-...", "target": "scope/plan#outcome", "relation": "needs", "fromOutcome": "optional", "evidence": "the sentence that justifies it", + "provenance": { "ownerRef": "...", "ownerMessageAt": "...", "recordedAt": "...", "operationId": "...", "itemDigest": "..." } } + ], + "deadline": { "date": "YYYY-MM-DD", "evidence": "...", "provenance": { } } + } + }, + "receipts": { "OPERATION": { "requestDigest": "...", "revision": "...", "recordedAt": "...", "result": { "action": "annotate", "ids": [] } } } +} +``` + +Objects are closed. An unknown key makes the file invalid. `check` reports it and `annotate` refuses to write until it is fixed by hand. Plans are never hidden by a broken sidecar. + +## Writing + +Only the owner route `mozak annotate` writes the file. It takes the scope lock, writes one temp file and renames it once. The CAS input is the sidecar token in `expectedAnnotations`. `graph` returns the current token per scope in `annotations`. A retried identical request replays its receipt. The same operation ID with other input is refused (`operation-conflict`). See `skills/mozak/references/routes.md` for the request shape and the item kinds. + +At write time each ref must resolve: the source plan and `fromOutcome` exist, the target scope is in the inventory, and the target plan (and outcome) exists or was merged into a live plan. A self reference and a duplicate ref are refused. + +Temp files are named `mozak.annotations.json..tmp`. `init` and `projection repair` add `mozak.annotations.json.*.tmp` to `.gitignore`. The next write removes a leftover one, and `check` lists it meanwhile. + +## Settings + +`mozak-settings.json` sits next to the inventory file. It is optional. There is one per installation. mozak never reads a `mozak-settings.json` inside a scope folder, because a scope folder can be a public repo. `check` reports such a file as `settings-scope-file-deprecated`. + +```json +{ "format": "mozak.settings/v1", + "concurrency": { "rebase": false }, + "scopes": { "research": { "annotations": true }, "anpit": { "concurrency": { "rebase": true } } } } +``` + +- Annotations are **off by default** (since 0.5.0). A scope without `"annotations": true` behaves like 0.4.7: `mozak.annotations.json` is never read, `graph`, `ready`, `plans --sort deadline`, `check` and the Obsidian sidebar ignore it, `mozak.md` does not change, and `annotate` is refused with `annotations-disabled`. +- Turn them on per scope with `scopes..annotations: true`. +- Repo-mode remote scopes are always refused. Their plans are pushed to a repository. `check` warns about a sidecar file found in one. +- `annotations.personalVaults` from older settings files is accepted and has no effect. +- `concurrency.rebase` turns on the experimental read-set rebase (see `docs/installation.md`, Parallel writes). A per-scope `scopes..concurrency.rebase` wins over the top-level value. The default is off. +- The key reserved for a later slice (`indexRoots`) is accepted. Any other key is a `settings-unknown-key` finding with no effect. +- A wrong value type or a missing `format` makes the file invalid. `annotate` then refuses with `settings-invalid`, `check` reports it, and rebase stays off. + +## Resolution + +A target `scope/plan[#outcome]` resolves in this order: + +1. The plan exists in the target scope. +2. A live plan recorded folding it in (`decision.mergedPlanId`). The ref then points at that plan. +3. Otherwise it is reported: `dangling` (scope not in the inventory, plan missing, outcome missing) or `unavailable` (the target scope cannot be read now). + +Reads never fetch for resolution. A remote scope is read from its local copy. + +## Deadlines from prose + +A date counts only when it directly follows a cue: `before`, `by`, `deadline`, `deadline is`, `due`, `until`, `rok`, `rok je`, `do`, `prije`. A weekday may sit in between, and a colon may follow the cue. Formats: `YYYY-MM-DD`, `D Mon YYYY`, `D. M. YYYY.`, `D. YYYY.` A date without a year is not a date. + +The rule reads the title, purpose, rationale, constraints and every outcome that is not done. Past dates are dropped. A completed plan has no deadline. One future date left gives an `inferred` deadline. Several give `candidates`, and the agent proposes one `deadline` item for the owner to pick. An owner deadline always wins. + +## Views + +- `mozak graph (--scope ID | --all)`: plans, refs and their resolution, with counts. +- `mozak ready (--scope ID | --all)`: open plans whose `needs` are met. A plan-level need blocks while the target plan is not completed. An outcome target blocks while that outcome is not done. A need from `fromOutcome` blocks only while that outcome is the plan's current outcome. Ready plans sort by deadline, then by how many plans need them. Plans superseded by a plan that is not rejected are listed apart. +- `mozak plans --sort deadline`: the usual groups, ordered by deadline. Rows gain `deadline` and `deadlineStatus`. +- MCP: `mozak_plan_graph`, `mozak_ready`, and `sort` on `mozak_plans`. There is no MCP annotate tool. +- The Obsidian sidebar lists outgoing and incoming refs under each plan row. + +## Check findings + +`ref-dangling`, `ref-target-unavailable`, `annotation-plan-missing`, `needs-cycle`, `needs-closed-target` (a need on a rejected or completed plan), `superseded-open` (an open plan superseded by an open plan), `superseded-next-action` (a superseded plan still has a next action), `annotations-invalid`, `annotations-on-remote`, `settings-invalid`, `settings-unknown-key`, `settings-unknown-scope`. Findings only. Nothing is repaired. + +## Limits + +- Prune records (`plan prune`, a later slice) are not consulted yet. A ref to a pruned plan is reported as dangling. +- `ready` and supersede detection only see refs stored in the selected scopes. Use `--all` to include refs from every scope. +- The deadline rule is lexical. It can pick a cued date that is not a deadline, for example "data until 2026-11-15". diff --git a/docs/assets/mozak-agent-chat.gif b/docs/assets/mozak-agent-chat.gif deleted file mode 100644 index 8b669d0..0000000 Binary files a/docs/assets/mozak-agent-chat.gif and /dev/null differ diff --git a/docs/assets/mozak-agent-chat.mp4 b/docs/assets/mozak-agent-chat.mp4 deleted file mode 100644 index d6c87c6..0000000 Binary files a/docs/assets/mozak-agent-chat.mp4 and /dev/null differ diff --git a/docs/assets/mozak-demo-still-v3.png b/docs/assets/mozak-demo-still-v3.png new file mode 100644 index 0000000..0a6a38c Binary files /dev/null and b/docs/assets/mozak-demo-still-v3.png differ diff --git a/docs/assets/mozak-demo.gif b/docs/assets/mozak-demo.gif deleted file mode 100644 index b497afa..0000000 Binary files a/docs/assets/mozak-demo.gif and /dev/null differ diff --git a/docs/assets/mozak-demo.mp4 b/docs/assets/mozak-demo.mp4 deleted file mode 100644 index bdc54be..0000000 Binary files a/docs/assets/mozak-demo.mp4 and /dev/null differ diff --git a/docs/audit-2026-10.md b/docs/audit-2026-10.md new file mode 100644 index 0000000..70706a4 --- /dev/null +++ b/docs/audit-2026-10.md @@ -0,0 +1,92 @@ +# Code audit, October 2026 + +First done on an agent branch in October (2026-10-21). Redone for 0.5.0 on `release/0.5.0` after the merge, because main had changed the same files since. The tighter compiler flags, the `typecheck`, `lint` and `loc` scripts, the shared path helper and the ten error messages that name the next step came in with the merge. The format-1 deletion is one commit on `release/0.5.0`. + +## How it was measured + +- Lines: `node scripts/count-loc.mjs` (or `npm run loc`) counts non-blank lines of `packages/*/src`. Add `--files --json` for a per-file list. +- Checks: `npm run build` (includes the typecheck), `npm run lint` (typecheck plus `node scripts/check-links.mjs`) and `npm test` under the default macOS `TMPDIR`, `TMPDIR=/tmp` and a realpath folder. + +| | Before the deletion | After | +| --- | --- | --- | +| Non-blank lines, `packages/*/src` | 11549 | 10889 (-660) | +| `packages/core/src` | 8996 | 8336 (-660) | +| `packages/cli/src` | 1163 | 1163 | +| `packages/mcp/src` | 450 | 450 | +| `packages/obsidian/src` | 940 | 940 | + +The test count drops because the tests of deleted code went with them. The `touched()` tests had already moved to `notes.test.ts` with the merge. + +## What was removed + +These modules implemented format 1 (`mozak.md` with `## Plan`, `## Links`, `## Translations`). No CLI route, MCP tool, plugin file or installer script imported them. They were reachable only through `export *` in `packages/core/src/index.ts`, from their own tests and from `scripts/demo.ts`. The format-1 routes in `api.ts` still refuse with `unsupported-legacy-operation`, so old clients get the same answer. + +| File | Non-blank lines | What it was | +| --- | --- | --- | +| `packages/core/src/parse.ts` | 136 | format-1 parser | +| `packages/core/src/graph.ts` | 123 | format-1 link graph and disk scan | +| `packages/core/src/stale.ts` | 128 | format-1 stale report. Its useful parts already moved to `notes.ts` and `locators.ts` in S6. | +| `packages/core/src/init.ts` | 95 | format-1 scaffold (already refused) and the old project audit draft | +| `packages/core/src/translate.ts` | 76 | format-1 translations | +| `packages/core/src/check.ts` | 58 | format-1 `checkScope` and the `CLAUDE.md` import check that only it used | +| `packages/core/src/write.ts` | 21 | retired raw writers that only threw, and `readSnapshot`/`hashText` used only by tests | +| `packages/core/src/plan.ts` | 11 | format-1 `setPlan` | +| `notes.ts` `wikiNames` | 4 | used only by `stale.ts` | +| `scripts/demo.ts`, `scripts/render_gif.py` | 54 and 74 raw lines | the format-1 launch GIF demo. It already failed, because `guardedWrite` throws. | + +Tests removed with that code: `graph`, `stale`, `parse`, `translate`, `init`, `write` and `plan` test files and `writer-child.ts`. + +## What changed + +- **One path helper.** `packages/core/src/paths.ts` has `realOrSelf` and `isWithin`. They replace four identical realpath-or-self copies (`settings.ts`, `plans-index.ts`, `locators.ts`, `local-sync.ts`), the plugin's own `realOrSelf` (now re-exported from core), and two identical "inside" checks (`local-sync.ts`, `usage.ts`). `usage.ts` keeps its `realish` as `resolve(realOrSelf(p))`, which is the same result. +- **Folding.** `noteKey` uses `foldKey` instead of repeating it. +- **Error messages.** A scan of `new DomainError(...)` calls found 154 sites with 70 codes. Eleven common codes had messages that did not say what to do next. They now end with the next step. Codes and exit codes are unchanged. `error-messages.test.ts` triggers each one. + +| Code | Added next step | +| --- | --- | +| `stale-input` | take the new snapshot from context as expected and use a new operationId | +| `operation-conflict` | use a new operationId for a changed request, or read the committed result with `mozak operation --id` | +| `scope-not-found` | run `mozak scopes` (MCP `mozak_scopes`) to list the scope ids | +| `plan-not-found` | run `mozak plans` (MCP `mozak_plans`) to list the plan ids | +| `busy` (read retries) | another writer is active, retry in a few seconds | +| `invalid-json` | restore `mozak.json` from git or fix the syntax by hand, then run `mozak check` | +| `scope-mismatch` (read) | names both ids, then: fix the inventory entry or its root | +| `scope-uninitialized` (local) | check its root in the inventory, or ask the owner to run `mozak scope init` | +| `bridge-unavailable` (write) | run `mozak check` to see why, and ask the owner to run `mozak projection repair` | +| `capacity-exceeded` | split the request, or for the 4 MiB state limit ask the owner to prune rejected plans or move finished plans | +| `continuation-stale` | request the first page again without a continuation | + +- **Types.** `tsconfig.base.json` now sets `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch` and `noImplicitOverride`. On the first branch that needed four removals of unused code and six `override` keywords in the plugin. Those came in with the merge, so on `release/0.5.0` the flags compiled with no further change. +- **Scripts.** `npm run typecheck` (`tsc -b`), `npm run lint` (typecheck plus the link check) and `npm run loc`. There is no other linter, on purpose. +- **CI.** `.github/workflows/ci.yml` runs build, tests and the installer suite on pull requests and pushes to `main`, on Ubuntu and macOS, with Node 24.11.0 and 26, read-only permissions and no secrets. It also runs `npm run lint` as its own step (owner commit `32f670b`), so a typecheck or link failure is named in the job. + +## Dependencies and licenses + +`npm ls --all --omit=dev` lists only the four workspace packages. mozak has no third-party runtime dependency. The plugin bundle contains core only; `obsidian` is provided by the app. + +`npm audit --omit=dev`: 0 vulnerabilities. `npm audit` including dev dependencies: 0 vulnerabilities. Nothing was fixed or upgraded. + +| Package | Version | License | Kind | +| --- | --- | --- | --- | +| `@mozak/core`, `@mozak/cli`, `@mozak/mcp`, `@mozak/obsidian` | 0.4.0 | MIT (repo `LICENSE`) | workspace, runtime | +| `typescript` | 5.9.3 | Apache-2.0 | dev | +| `@types/node`, `undici-types` | 22.20.5, 6.21.0 | MIT | dev | +| `esbuild`, `@esbuild/darwin-arm64` | 0.28.2 | MIT | dev (plugin build) | +| `obsidian` and its type deps (`@codemirror/state`, `@codemirror/view`, `@types/codemirror`, `@types/tern`, `@types/estree`, `moment`, `crelt`, `style-mod`, `w3c-keyname`, `@marijn/find-cluster-break`) | various | MIT | dev (types for the plugin) | + +## What was left, and why + +- **Test scratch helpers.** About 25 test files define their own `scratch` folder. They differ on purpose: some require `TMPDIR`, some fall back to `tmpdir()`, some resolve symlinks. Merging them is not a pure refactor. +- **`locators.ts` `inside`.** It compares path prefixes, not `relative()`. The two give different answers for unnormalized paths, so it was not merged into `isWithin`. +- **Stricter flags not turned on.** `noUncheckedIndexedAccess` gives 46 errors and `noPropertyAccessFromIndexSignature` gives 820. `exactOptionalPropertyTypes` gives one error, but it changes what optional fields mean, so it should be a separate decision. +- **`SPEC.md`.** It still describes format 1. `docs/README.md` already lists it as a superseded historical record. +- **`docs/demo.gif`.** Nothing links to it. It looks like the old format-1 demo. Removing a binary is left to the owner. +- **Package metadata.** No `package.json` has a `license` field. The repo `LICENSE` is MIT. Adding the field also changes `package-lock.json`, so it is left for a release commit. +- **`@types/node` 22** while `engines` asks for Node 24.11 or newer. Upgrading types is a dev change for a separate commit. +- **`release.yml`** uses `actions/checkout@v4` and `actions/setup-node@v4` by tag, not pinned to a commit like `ci.yml`, and it needs `GITHUB_TOKEN` to publish. It was not changed. + +## Open risks + +- The removed exports were part of `@mozak/core`'s `index.ts`. No package in this repo uses them. Any outside code that imported them would break. +- The compiler flags apply to every later change. Unused locals or a missing `override` now fail the build. +- The local checks ran on macOS with Node 26 only. Linux and Node 24 run in CI. diff --git a/docs/installation.md b/docs/installation.md index 2c1c989..e546e7a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -8,6 +8,7 @@ This guide covers building mozak from source, the portable installer, exit codes | --- | --- | | Pending-revision summary order and safe projection recovery | Verified 2026-10-29 on macOS, Node 26.11.1: build passed, all 495 tests passed, installer suite 73 passed and 1 skipped (case-sensitive filesystem required). Three built-CLI regressions and two core tests cover deterministic field order, official repair, unchanged canonical bytes and review subject, repeat repair, legacy filenames, merge metadata, and refusal of other edits. Test-first: CLI revision initially exited 5 with its own `bridge-conflict`; after sorting, recovery still failed `bridge-conflict` versus `bridge-stale` until the recogniser was added. With focused Node coverage, crapper scored the new recogniser 1.0, `pendingChangedFields` 8.1, `isOlderRender` 3.0 and `projectStatus` 7.1; unrelated existing functions still exceed 10. Dryer found no duplicate candidates at 0.8 across the three changed source files. Mutator killed all three selected recogniser mutants (not a whole-repo mutation run). Existing plugin CJS `import.meta` warnings remain. No live scope or installation was changed. | | Fresh public GitHub clone, build, install and README walkthrough on macOS, Node 26.11.1 | Verified 2026-10-18 at `8337e04`: clean `git clone`, `npm ci --ignore-scripts`, build and install into a fresh prefix with an isolated `HOME` took about 8 seconds. Every README command then ran as written (section 8). | +| Full test suite on macOS, Node 26.10.0 and 24.11.0 | Verified 2026-11-01 on `release/0.5.0` (`9c26892`, version 0.5.0): 630 tests passed with three `TMPDIR` settings on each Node version, installer suite 73 passed and 1 skipped. Details and the verifier numbers are in [section 8](#8-verification-status). | | Full test suite on macOS, Node 26.10.0 | Verified 2026-10-31 on branch `vnext/2a-fixes` (`b8e0f71` plus the 0.4.8 version bump, not yet merged or tagged): `npm ci --ignore-scripts && npm run build`, then `npm test` with `JCODE_SCRATCH_DIR` unset: 539 tests passed, 0 failed, with the default macOS `TMPDIR`, with `TMPDIR=/tmp` and with a realpath folder. Installer suite 73 passed, 1 skipped (case-collision test needs a case-sensitive filesystem). `npm run build:npm` built a package reporting 0.4.8, and the built CLI reports 0.4.8. New tests cover P0.1, P0.2, P0.5 to P0.7 (including `plan delete` under a concurrent edit), the SPEC banner and README network disclosure, accepted outcomes after late support, MCP error text, and a vault opened through a symlink. Not run on Linux or in CI. | | Full test suite on macOS, Node 26.11.1 | Verified 2026-10-29 at `a8e0fa9` plus the 0.4.7 version bump: 497 tests passed, 0 failed. Installer suite 73 passed, 1 skipped (case-collision test needs a case-sensitive filesystem). New tests: `attach-spec` computes an omitted `discussionDigest` and refuses a stale supplied one, and `observe` flag errors list the allowed values for activity-kind, relation, classification and verdict. | | Source build and tests on Linux, Node 24.11.0 | Verified earlier at `c324d45`: 334 core tests and 69 installer tests passed. CI covers Linux on every push since. | @@ -233,7 +234,49 @@ mozak never steals a write lock because it is old. Follow this order: 5. Run `context` and `check`, which only read. If the scope state exists, run `projection repair` against the current snapshot. 6. If a bridge was edited by hand, it is kept as a conflict. Resolve it with the owner before writing again. -There is no online force-unlock command. +There is no force-unlock command. The owner route `mozak recover` removes one named lock only in two cases where no +local writer can still own it: + +- the lock's `owner.json` names another host (`host` is recorded since S2). Such a lock can only have arrived by sync, for example through a `git add -A` in a vault. +- it names this host and a pid that is no longer running. + +`check` reports a stuck lock as `write-lock-stuck` with its `token`, `host`, `pid` and `verdict`. The owner repeats those +in a request file: `{ "requestId", "scopeId", "lock": { "token", "host", "pid" }, "ownerRef", "ownerMessageAt" }`, then runs +`mozak recover --scope ID --request FILE`. It refuses a lock that changed, a lock with contents other than `owner.json`, +a live local pid (`lock-owner-alive`), and a lock without a host from an older mozak (`lock-host-unknown`, remove that +one by hand as above). It never touches `mozak.json`. Agents cannot run it, and the MCP server does not offer it. + +### Projection tolerance + +A `mozak.md` that differs from the current render only by CRLF line endings, trailing spaces or tabs, or blank lines at +the end counts as current, not as a bridge conflict. The next write puts back the exact render. Any other difference, +including leading or inner whitespace, is still a conflict. + +### Pruning rejected plans: `mozak plan prune --rejected` + +Owner route. The request lists the plan ids the owner saw: `{ "operationId", "scopeId", "expected", "planIds", "ownerRef", "ownerMessageAt" }`. +Only plans that were never accepted and whose revision is rejected can be pruned. A plan another plan still references (a +pending merge, a reasoning link) is refused with `prune-referenced`. The write is a normal CAS write and is never rebased. +Its receipt `{ "action": "prune-rejected", "ids": [...] }` is the prune record: owner refs to a pruned id resolve as +`pruned` (with the operation id), `check` reports `ref-target-pruned`, and the id cannot be proposed again. A 0.4.0 +client reads such a scope unchanged. + +### Hand edits: `mozak check --history N` + +Every mozak write sets a new `storage.revision` and records it in a receipt. `check --history N` walks the last N commits +(1 to 500) that touched the scope's `mozak.json`, from local git objects only, and reports `hand-edit` for a commit that +changed the file but kept the revision (with removed and added plan ids), and `hand-edit-revision` for a revision that no +receipt records. Outside git it reports `history-unavailable` and skips the walk. + +### Syncing a vault: `mozak sync --scope ID` or `mozak sync --local` + +For a local scope inside a git repo, `sync` replaces a bare `git pull --rebase`, which bypasses the scope locks. Per repo +it fetches the upstream of the current branch outside the locks, takes the write lock of every inventoried local and +vault-plans scope in that repo in path order, runs `git merge --ff-only`, and releases. It never rebases, merges a +diverged history or pushes. Row status: `fast-forwarded`, `up-to-date`, `ahead` (local commits to push), or a problem: +`not-fast-forward` (exit 3, nothing changed), `busy` (exit 4, a scope lock is held), `fetch-failed`, `merge-failed`, +`no-upstream`, `detached`, `not-in-git`. `--local` syncs every such repo and the remote scopes; plain `mozak sync` still +syncs remote scopes only. ### Projection repair @@ -241,6 +284,28 @@ If a write saved the JSON but not the generated `mozak.md` bridge, the result sa Versions through 0.4.6 could also produce a conflict themselves after revising several fields: the pending-summary field list followed request key order, while the saved JSON used sorted keys. New renders sort that display list. Repair recognises an old list only when reordering its known field labels makes the entire file exactly match the current render of the same graph. Outcome counts, merge metadata, graph hash and every other byte must match. Other hand edits remain conflicts and are preserved. Repair changes only `mozak.md`, not plan content, approval subjects or review digests, and a repeat reports `already-current`. +### Parallel writes: `concurrency.rebase` (experimental, off by default) + +Every write names the snapshot it was based on. By default any other write in between makes it `stale-input` (exit 3), even when the two writes do not touch the same thing. A scope can opt in to read-set rebase in the `mozak-settings.json` next to the inventory file (the same file as the annotation settings, see `docs/annotations.md`): + +```json +{ "format": "mozak.settings/v1", + "concurrency": { "rebase": false }, + "scopes": { "my-scope": { "concurrency": { "rebase": true } } } } +``` + +A per-scope value wins over the top-level `concurrency.rebase`. A missing or invalid file keeps the default (off), and `check` reports an invalid one. A `mozak-settings.json` inside a scope folder is not read. `check` reports it as `settings-scope-file-deprecated`. + +With rebase on, a stale write can still commit onto the fresh state when it only appends: + +- `observe`: each linked outcome keeps its revision and display status, no one else superseded the same observation, and its ids are still free. +- `save-discussion`: that plan's discussion was not saved in between. +- `propose` of a new id: the id is still free. The duplicate check runs on the fresh state. + +Owner decisions, `revise`, `complete` and `attach-spec` are never rebased. Any of them in between also refuses the rebase. Only a snapshot equal to the current revision or to a retained receipt's revision can rebase. A rebased result carries `rebased: { from, onto }` and the fresh `snapshot`, so the next write needs no reread. A refused rebase is a normal `stale-input` with the reason in the message. + +Limits: the writes in between are found through receipt times. A write merged by git from a machine whose clock is behind can be missed, so a non-rebasable receipt up to 1 second before the snapshot's receipt also refuses. Hand edits to `mozak.json` that keep the same revision always refuse. + ## 6. Safety rules - **No secrets in this repo.** Do not paste tokens, passwords, or keys into files, commands, or chat. The installer never copies credentials. @@ -249,6 +314,20 @@ Versions through 0.4.6 could also produce a conflict themselves after revising s - **Use only the scopes you list.** The inventory file is explicit. Every CLI and MCP call needs `--config FILE`. The MCP server needs it at startup. - **Do not onboard real projects while testing.** Use an isolated test folder and synthetic data. +## 6a. Focus list + +Every scope entry in the inventory, local or remote, may carry `focus`: an array of unique plan ids the owner starred. The Obsidian sidebar shows them in its Focus tab. + +```json +{ "id": "atlas-app", "root": "./atlas-app", "focus": ["launch", "billing"] } +``` + +- `mozak focus list [--scope ID] [--json]` reads the lists. MCP has the read-only tool `mozak_focus`. Agents cannot write focus. +- `mozak focus add|remove --scope ID --plan ID` (owner) and the sidebar star change one list. The write takes the inventory lock (`.mozak-inventory-lock` next to the inventory file), writes a flushed temp file, checks it with the normal inventory loader, then renames it into place. Entry order, indent and every other key (including `x`) stay as they were. `add` refuses an unknown scope or plan. Adding twice or removing an id that is not there changes nothing. +- Focus is not plan state. `mozak.json` and `mozak.md` never change, and the inventory digest (format plus sorted id and root) ignores it. +- A starred id that is no longer a plan is a `check` warning (`focus-unknown-plan`), never an error. Remove it with `mozak focus remove`. +- mozak before 0.5.0 refuses an inventory with `focus` (`unknown key "focus"`). Upgrade every machine that reads the inventory before starring a plan. + ## 6b. Remote scopes A scope can live in a GitHub repo instead of a local folder. List it with `remote` and no `root` (exactly one of the two), in a `mozak.local/v3` inventory. `v2` inventories still load unchanged. @@ -287,11 +366,17 @@ Cache layout: `.mozak-cache//` (sparse git clone) and `.mozak-cache/.met - Upgrading needs the source checkout the installation came from (or `--source PATH`), and only knows release tags of that checkout's `origin`. - The source copy of the conversation skill is a template. The installer refuses an unrendered template. Load the skill only from the installed folder, directly or through a symlink. - Older scope formats are refused. mozak does not migrate them. +- `mozak similar` is lexical. It finds copies and near copies, and supersession only when the newer plan names the older one or the older one was rejected. Plans that mean the same thing in different words are not found. ## 8. Verification status | Check | Status | | --- | --- | +| 0.5.0 full gate on `release/0.5.0` (`9c26892`, 2026-11-01, macOS 27 arm64, Node 26.10.0 and Node 24.11.0) | Passed on both Node versions: `npm ci --ignore-scripts`, `npm run build`, then `npm test` with `JCODE_SCRATCH_DIR` unset, 630 of 630 with the default macOS `TMPDIR`, with `TMPDIR=/tmp` and with a realpath folder. `npm run test:install` 73 passed, 1 skipped (case-collision test needs a case-sensitive filesystem). `npm run typecheck` and `npm run lint` (33 Markdown files, 61 relative links, 0 broken) passed. `npm run build:npm` built `mozak 0.5.0` and its CLI prints `0.5.0`. The version check from `release.yml`, run locally for tag `v0.5.0`: package, root manifest and plugin manifest all `0.5.0`, all three plugin assets present. Linux runs in CI on the pull request. | +| 0.5.0 verifiers (same commit, both Node versions) | V-race, V-ref and V-dup tests (`rebase.test.ts`, `scope-process.test.ts`, `vref.test.ts`, `vdup.test.ts`): 41 of 41. `node scripts/verify-dup.ts`: precision 1.000, recall 0.988, 0 templated duplicates. `node scripts/verify-latency.ts` (23 synthetic scopes, 230 plans): `plans.md` max 19.5 ms (budget 1000), CLI 62 ms, 460 locators max 25.3 ms (budget 300). | +| 0.5.0 large-store stress, V-race 9 at 1000 write attempts (Node 26) | `MOZAK_VRACE_KILL_OPS=1000`, 8 writers, think 1 to 2 s, rebase on, kill -9 once per round. Two runs: 1007 and 1003 attempts, 605 and 609 commits, 0 violations, 31 of 31 locks left by killed writers cleared by `recover`, commit p50 95.2 and 100.1 ms, **p95 222.9 and 219.6 ms** (target 300 ms), max 629.4 and 649.5 ms. V-race 1 (3 agents x 10): flag off 46 of 76 attempts wasted, flag on 0 of 30, 0 lost either way. | +| 0.5.0 old client and upgrade (scratch prefixes only) | `scripts/verify-old-client-sidecar.sh` with `OLD_CLI` set to a scratch install of `v0.4.7`: the old CLI reads, checks and writes a scope with an annotations sidecar, the sidecar is unchanged, and the branch reads one edge with 0 dangling. `mozak upgrade` from a scratch `v0.4.7` install against a local mirror tagged `v0.5.0`: `upgraded`, `mozak --version` 0.5.0, the plugin in a scratch vault went from 0.4.7 to 0.5.0, the old install kept as `mozak.previous-0.4.7`, the source checkout back on its branch and clean, and a second run reported `up-to-date`. | +| 0.5.0 on real plan data (read only, copies) | 26 local and vault-plans scopes copied from the owner's inventory (1 GitHub repo scope without a local copy skipped). `render --all` with the branch reported all 26 current, `check` found 0 issues in each, and a fresh render of every `mozak.json` with the 0.4.7 core and the 0.5.0 core is byte-identical to the stored `mozak.md` (26 of 26). `context --brief` on the real `mozak` scope through a scratch install: 6168 bytes. Focus on a copy of the inventory: add, idempotent add, list, unknown plan refused with exit 2, only the `focus` key changed; 0.4.7 refuses the starred inventory with `unknown key "focus" in scope entry` (expected); removing the last plan leaves `"focus": []`. | | P0.5 to P0.7 storage hygiene on `vnext/2a-fixes` (2026-10-31, macOS, Node 26) | Passed: `npm test` with `JCODE_SCRATCH_DIR` unset, 529 of 529 with the default macOS `TMPDIR`, with `TMPDIR=/tmp` and with a realpath folder. P0.5: `init` and projection repair add the write-lock and temp-file ignore lines, `check` reports `lock-not-ignored` and `lock-in-git`. P0.6: `mozak.json` and `mozak.md` are hashed again right before each rename (`graph-changed-during-write`), for propose, retitle, init and `plan delete` (a new delete test failed before the fix and passes after). P0.7: a reserved `x` object in the inventory or a scope entry is accepted and reported as `inventory-x-ignored`. The rename check narrows the direct-editor race, it does not close it. | | P0.1 duplicate bypass and P0.2 merge capacity on `vnext/2a-fixes` (2026-10-31, macOS, Node 26) | Passed: `npm ci --ignore-scripts && npm run build`, then `npm test` with `JCODE_SCRATCH_DIR` unset: 510 of 510 with the default macOS `TMPDIR`, with `TMPDIR=/tmp` and with a realpath folder. Exact copies with different id numbers are now refused as `duplicate-plan-candidate`, and a merge over 32 discussion questions is refused as `merge-capacity` at propose and at approval instead of being cut. Two existing fixtures that repeat one direction on purpose pass `distinctFromPlanIds`. | | Agent ergonomics on `vnext/2a-fixes` (2026-10-31, macOS, Node 26) | Passed: `env -u JCODE_SCRATCH_DIR node --import ./scripts/test-git-isolation.mjs --test --experimental-strip-types packages/cli/test/agent-ergonomics.test.ts`: 11 of 11 (decide, delete and observe flag forms, dry-run writes nothing, provenance required, `--spec` mismatch refusal, revise and decide warnings, `plan show` size and fields, MCP `mozak_decide` off by default, help lists the flag forms, invalid observe kinds). Part of the full suite below. Measured on synthetic temp scopes only. | diff --git a/docs/obsidian-roadmap-spec.md b/docs/obsidian-roadmap-spec.md index 31babd2..a9bf661 100644 --- a/docs/obsidian-roadmap-spec.md +++ b/docs/obsidian-roadmap-spec.md @@ -44,7 +44,7 @@ Purpose text. ### Roadmap ```mermaid flowchart LR - s1["✅ Concept doc"]:::done --> s2["🟡 Mini cleanup"]:::evidence --> s3["📍 Hermes sandbox"]:::current --> s4["Dogfood RAG"]:::todo + s1["✅ Concept doc"]:::done --> s2["🟡 Mini cleanup"]:::evidence --> s3["📍 Agent sandbox"]:::current --> s4["Dogfood RAG"]:::todo classDef done fill:#22a55b,color:#fff classDef evidence fill:#e8b931,color:#000 classDef current fill:#8b5cf6,color:#fff diff --git a/docs/obsidian-submission-checklist.md b/docs/obsidian-submission-checklist.md new file mode 100644 index 0000000..d484973 --- /dev/null +++ b/docs/obsidian-submission-checklist.md @@ -0,0 +1,67 @@ +# Obsidian community plugin submission checklist + +Status of the mozak plugin against the Obsidian community directory rules. First checked on 2026-10-21 at version 0.4.0. Rechecked on 2026-11-01 for 0.5.0 on the `release/0.5.0` branch. The plugin is already listed in the directory ([community.obsidian.md/plugins/mozak](https://community.obsidian.md/plugins/mozak)), so 0.5.0 is an update, not a new submission: Obsidian picks up a new GitHub release whose tag equals the manifest version. The owner publishes. No agent signs in to the owner's Obsidian or GitHub account. + +Sources, read on 2026-10-21 from [obsidianmd/obsidian-developer-docs](https://github.com/obsidianmd/obsidian-developer-docs) (`main`): + +- [Submit your plugin](https://docs.obsidian.md/Plugins/Releasing/Submit+your+plugin) +- [Submission requirements for plugins](https://docs.obsidian.md/Plugins/Releasing/Submission+requirements+for+plugins) +- [Developer policies](https://docs.obsidian.md/Developer+policies) +- [Plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines) + +Status key: **Met** means checked in this repo. **Owner** means only the owner can do it. **Check** means met as far as a file check can tell, but the owner should confirm by hand. + +## Files and release + +| # | Requirement | Status | Evidence or owner action | +| --- | --- | --- | --- | +| 1 | `README.md` at the repo root that says what the plugin does and how to use it. The directory shows an excerpt and rewrites relative links and images. | Met | Root `README.md`. The plugin section is "See everything in Obsidian". Relative image `docs/assets/mozak-hero-wide.png` exists. | +| 2 | `LICENSE` at the repo root. | Met | MIT. Checked by the test in `packages/obsidian/test/model.test.ts`. | +| 3 | `manifest.json` at the root of the default branch. The directory reads it at HEAD of the default branch. | Met on `release/0.5.0` | Root `manifest.json` equals `packages/obsidian/manifest.json` (test). The directory sees 0.5.0 once `main` is fast-forwarded to the release branch. | +| 4 | `id` is unique among published plugins and does not contain `obsidian`. | Met | `id` is `mozak`, listed in the directory. | +| 5 | `version` is `x.y.z`. | Met | `0.5.0`. | +| 6 | A GitHub release whose tag equals the manifest `version`, with `main.js`, `manifest.json` and `styles.css` attached. | Owner | `.github/workflows/release.yml` builds on a `v*.*.*` tag, refuses a tag that does not match `package.json` and both manifests, runs the tests, creates the exact-version plugin tag (`0.5.0`) on the same commit and attaches the three files with build provenance. Push `v0.5.0`, then check the release page. | +| 7 | `versions.json` (optional) maps plugin versions to the lowest Obsidian version. | Met | `"0.5.0": "1.14.4"`, the same `minAppVersion` as every 0.4 release (test in `packages/obsidian/test/submission.test.ts`). | + +## Manifest and code rules + +| # | Requirement | Status | Evidence or owner action | +| --- | --- | --- | --- | +| 8 | Only use `fundingUrl` for donations. | Met | No `fundingUrl`. | +| 9 | Set an appropriate `minAppVersion`. | Met | `1.14.4`, the version the owner runs (since 0.4.0). | +| 10 | Description: 250 characters or less, ends with a period, no emoji, correct capitalization. Starting with an action verb is recommended. | Met | "Project scopes and plans shared with AI agents, stored as plain files." (70 characters). Optional: an action wording such as "Show the plans you share with AI agents, stored as plain files, in a sidebar." Change both manifests if you want it. | +| 11 | `isDesktopOnly: true` when Node.js or Electron APIs are used. | Met | `true`. The plugin uses `node:fs`, `node:path`, `node:os` and `node:child_process`. | +| 12 | Command IDs do not include the plugin ID. | Met | One command, `open-scopes`, named "Open scopes". | +| 13 | Remove the sample plugin code. | Met | No sample classes or settings in `packages/obsidian/src`. | +| 14 | No `innerHTML`, `outerHTML` or `insertAdjacentHTML`. | Met | Checked by the test. | +| 15 | No needless console logging. | Met | No `console.log`, `debug` or `info` (test). | +| 16 | No default hotkeys. | Met | Test. | +| 17 | Sentence case in UI text, no "settings" in settings headings. | Met | "Open mozak scopes", "Inventory path", "Auto-refresh", "Repo sync interval (seconds)", "Sync vaults and repos", tabs "Open", "Focus", "Done", star labels "Add to Focus" and "Remove from Focus". The settings tab has no heading. | +| 18 | Clean up resources on unload, and do not detach leaves in `onunload`. | Met | `onunload` stops the file watchers and clears the sync interval. Leftover leaves of the retired plan view are closed on layout ready, not on unload. | +| 19 | No hardcoded inline styles. | Met | No `.style` assignments in `src`. Styling is in `styles.css`. | + +## Developer policies + +| # | Requirement | Status | Evidence or owner action | +| --- | --- | --- | --- | +| 20 | No obfuscated code. | Met | `main.js` is an esbuild bundle, not minified. | +| 21 | No ads. No client-side telemetry. | Met | None. | +| 22 | Does not install or update itself or its dependencies. | Met | The plugin only reads the update cache (`cachedUpdateNotice`). The bundle has no release-tag fetch and no `spawn(` (test). Updates come through Obsidian or `mozak upgrade`. | +| 23 | Disclose network use: which services and why. | Met | `packages/obsidian/README.md`, "Disclosures": `git fetch` for remote scopes (default every 60 seconds while Auto-refresh is on), the sync button's fast-forward of local vault repos, the unauthenticated GitHub API visibility check (at most once a day per repo), and the update notice, which reads a local cache only. | +| 24 | Disclose access to files outside the vault, and why. | Met | Same section: the scope files the inventory names (`mozak.annotations.json` only for scopes with annotations on), the upward lookup for `mozak-inventory.json`, and what the plugin writes: a stale `mozak.md` it regenerates, and the `focus` lists in `mozak-inventory.json` through the star. It never writes plan state. | +| 25 | Disclose payments, accounts, ads and server-side telemetry if any. | Met | None. The README says so. | +| 26 | Include a license and respect the licenses of bundled code. | Met | The bundle contains mozak's own `@mozak/core` and esbuild helpers. `obsidian`, `electron` and Node built-ins are external. The fonts with OFL notices are in `docs/assets/brand/` and are not bundled. | +| 27 | Do not suggest the plugin is made by Obsidian. | Met | The plugin name is "mozak". The headline is "One approved plan per project, shared by your coding agents, visible in Obsidian." | +| 28 | Not a fork. | Met | Original code. | + +## Risks for the automated review + +- **A. Update and spawn code in the bundle.** Fixed in 0.4.x: the plugin bundle has no release-tag fetch, no refresher script and no `spawn(` (test `the plugin bundle has no update refresher` in `packages/obsidian/test/model.test.ts`). +- **B. `child_process` use.** The plugin runs `git` for remote scopes and the sync button, and `curl` for the public visibility check. It is disclosed. Reviewers sometimes ask why. The answer: mozak reads plan files from your own git remotes with your existing login. +- **C. Writes outside plan state.** New in 0.5.0: the star edits `mozak-inventory.json`. It is disclosed in row 24 and in both READMEs. + +## What the owner does for 0.5.0, in order + +1. Fast-forward `main` to `release/0.5.0` after CI is green, so the root `manifest.json` and both READMEs with the new disclosures are on the default branch. +2. Tag `v0.5.0`. The release workflow checks the versions, creates the `0.5.0` plugin tag and attaches `main.js`, `manifest.json` and `styles.css` (row 6). +3. Check the release page, then update the plugin from Settings, Community plugins on one vault to confirm Obsidian offers 0.5.0. diff --git a/docs/plans-index.md b/docs/plans-index.md new file mode 100644 index 0000000..d9e68ef --- /dev/null +++ b/docs/plans-index.md @@ -0,0 +1,75 @@ +# Plans index, locators and similar plans + +Four read-mostly helpers for finding plans and what they cite. None of them stores state or uses a model. + +## `mozak plans-md`: a plans.md per repository + +``` +mozak plans-md --config INVENTORY --print # show the files, write nothing +mozak plans-md --config INVENTORY # owner: write them +``` + +- One `plans.md` per git repository that holds scopes, at that repository's root. A repository lists only its own scopes, so a company vault's file never names a personal plan, and the other way round. +- It holds titles and states only: open, paused, awaiting approval, completed. No purposes, outcomes, evidence or decisions. Rejected drafts are left out. +- The first line marks the file as generated. A `plans.md` without that line is never overwritten: the run reports `plans-md-conflict` (exit 3) and leaves it as it is. Same content means no write. +- Repo-mode remote scopes and scopes outside git are skipped and listed under `skipped`. +- Writing is an owner route. `--print` is a read, and agents may call it. mozak does not commit the file; commit it with the vault like any other note. + +## `mozak locators`: where citations point + +``` +mozak locators --config INVENTORY (--scope ID | --all) [--plan ID] [--include-private] [--json] +``` + +Every `Source.locator` and `Evidence.locator` of the selected plans, with what it points to on this machine: + +| status | meaning | +| --- | --- | +| `resolved` | a file or folder was found. `title` is its first heading or file name. For a Markdown note with an anchor, `anchorFound` says whether a heading matches it. | +| `missing` | looks like a path or a `[[note]]` link, nothing found | +| `ambiguous` | a `[[note]]` name matches several notes, none in the citing scope | +| `remote` | a relative path in a scope whose code lives in a remote repo that is not cloned here | +| `external` | a URL or a `git:` object, not checked | +| `not-checked` | prose, such as an owner message or a command | + +Relative paths are tried against the scope folder, its repository root, and the index roots. `[[note]]` links use a note index built from the index roots for this call. Note names match without case and with Croatian letters folded (`č ć` to `c`, `š` to `s`, `ž` to `z`, `đ` to `d`). Wikilinks inside code fences and code spans do not count. + +### Index roots and privacy + +`indexRoots` in the `mozak-settings.json` next to the inventory lists the folders to search: + +```json +{ "format": "mozak.settings/v1", + "indexRoots": [ { "path": "../vault/personal", "private": true }, { "path": "../vault/research" } ] } +``` + +Paths are relative to the settings file. Without `indexRoots`, the roots are the top folders of each git repository that holds a scope. A folder named `personal` is private. A scope whose folder is a repository root (a shared company vault) is not a root; its own citations still resolve inside its own folder. + +A file in a private root returns path and title only. `--include-private` (MCP and API: `includePrivate`) returns the excerpt too, and the usage log (when turned on with `MOZAK_USAGE_LOG=on` or `"usageLog": true` in `mozak-settings.json`) records that the call asked for it. Other files outside every root also return path and title only. + +## Cited-note staleness in `mozak check` + +`check` lists `cited-note-changed` for each file a live plan cites (source or evidence) that changed after the citation. Time comes from git. A citation counts from the first commit of the scope's `mozak.json` at or after its `observedAt` or `inspectedAt`, so a note committed while the citation itself was still uncommitted is not reported. Uncommitted edits count by file time. Files outside git are not judged. + +These lines are information, like leftover temp files. They never change the exit code: a changed note does not mean the edit matters. + +## `mozak similar`: similar and duplicate plans + +``` +mozak similar --config INVENTORY (--scope ID | --all) [--json] +``` + +MCP: `mozak_similar`. It pools every plan of the selected scopes and runs the same rules as the propose guard, with Croatian letters folded. A pair is reported only when at least one side is open, paused or awaiting: two completed or two rejected plans leave nothing to decide. + +- **Template filter.** Two plans with the same outcome-id list and fewer than 2 shared title words are siblings from one template, not a match. +- **`duplicate`.** Same content, or at least 60% of the body words shared and every title word of each plan found in the other. +- **`supersedes-candidate`.** The newer plan names the older one, or the older one was rejected. `a` is the newer plan. +- **`overlap`.** Any other match. +- **`moved`.** Rejected plans whose rejection reason says "moved to", listed apart. + +The report suggests; it never merges, rejects or links. Merges stay in one scope with `plan revise` and `mergeFromPlanId`. A cross-scope duplicate is usually a move: copy the plan, then reject the old one with a reason that says where it moved. + +## Verifiers + +- `node scripts/verify-dup.ts` builds the public synthetic mirror (12 bases, a third Croatian, exact copies under neutral ids, 60 mutations, templated siblings, a supersession pair, a moved reject) and checks: every exact copy is refused by `propose` in its own scope and labelled `duplicate` across scopes, the supersession pair is a `supersedes-candidate`, no templated pair is a `duplicate`, and `duplicate` precision is at least 0.95. `--config FILE` runs read only on a real inventory and fails above 4 pooled pairs (`--max-pairs N`). Exit 1 on any failure. `packages/core/test/vdup.test.ts` runs the mirror on every commit. +- `node scripts/verify-latency.ts [--config FILE]` times `plans.md` (budget 1 s, in process and through the CLI) and resolving every locator (budget 300 ms), on 23 synthetic scopes or a real inventory, read only. Exit 1 over budget. diff --git a/docs/release-notes-draft.md b/docs/release-notes-draft.md new file mode 100644 index 0000000..707d780 --- /dev/null +++ b/docs/release-notes-draft.md @@ -0,0 +1,50 @@ +# mozak 0.5.0 release notes (DRAFT) + +> **DRAFT.** Not published and not tagged. The owner edits, approves and publishes this. Numbers below come from [installation.md, verification status](installation.md#8-verification-status). Recheck them on the release commit. + +## In one line + +A Focus tab for the plans you care about now, shorter context reads for agents, and safer storage, with every new switch off until you turn it on. + +## Highlights + +- **Focus tab in Obsidian.** The sidebar tabs are now Open, Focus and Done. Star a plan to put it in Focus. The star writes a `focus` list on that scope's entry in `mozak-inventory.json`, the same as `mozak focus add|remove`. Agents can read it with `mozak focus list` or MCP `mozak_focus` but never change it. Focus is a sidebar marker only, not plan state. +- **Shorter reads for agents.** `mozak context --brief` gives one short summary per plan. `mozak context --plan ID` gives the full state of one plan. Both work in the MCP tool `mozak_context`. +- **Links and deadlines between plans, off by default.** The owner can record that a plan needs, informs or supersedes another, and set deadlines, with `mozak annotate`. `mozak graph`, `mozak ready` and `mozak plans --sort deadline` read them. Turn them on per scope in `mozak-settings.json`. They live in a separate `mozak.annotations.json`, so `mozak.json` and `mozak.md` do not change. See [annotations.md](annotations.md). +- **Plans index, locators and similar plans.** `mozak plans-md` writes a `plans.md` with plan titles and states at each notes repo root. `mozak locators` shows where each source and evidence locator points, and `check` lists cited notes that changed after they were cited. `mozak similar` reports duplicate, overlapping and superseding plans across scopes. See [plans-index.md](plans-index.md). +- **Safer storage.** `scope init` and `projection repair` add ignore lines for the write lock and temp files, and `check` warns when the lock is not ignored or is tracked by git. A write refuses if the files changed under it right before the replace. `mozak recover` clears a stuck lock, `mozak plan prune --rejected` removes rejected plans, `mozak check --history N` finds hand edits, and `mozak sync --local` fast-forwards your vaults. +- **Parallel agents (experimental, off by default).** With `concurrency.rebase` on, a stale append (an observation, a discussion save, a new plan) can commit onto the fresh state when nothing it read has changed. +- **Fixes.** The duplicate-plan guard catches copies that differ only in ID numbers. Plan merges refuse to drop discussion questions. A late supporting observation keeps an accepted outcome done. The Obsidian plugin opens plans in a vault opened through a symlink. +- **Smaller core.** The unused format-1 modules are gone, error messages say what to do next, and the compiler runs stricter checks. + +The full list is in [CHANGELOG.md](../CHANGELOG.md). 0.5.0 includes the fixes prepared as 0.4.8, which was never tagged. + +## Upgrade + +```bash +mozak upgrade --vault ~/path/to/your/vault +mozak doctor --fix +``` + +Nothing changes in existing scopes until you use a new feature. + +**Upgrade every machine before you star a plan.** mozak before 0.5.0 refuses an inventory that has a `focus` list (`unknown key "focus"`). If one machine stars a plan while another still runs 0.4.x, that older mozak stops reading the shared inventory until it is upgraded. + +Off unless you turn them on in the `mozak-settings.json` next to the inventory: owner annotations (`scopes..annotations: true`), `concurrency.rebase` (top level or `scopes..concurrency`) and the counts-only usage log (`"usageLog": true`, or `MOZAK_USAGE_LOG=on`). Read [installation.md](installation.md#parallel-writes-concurrencyrebase-experimental-off-by-default) before you turn rebase on. + +## Known limits + +- `concurrency.rebase` relies on receipt times. A write merged by git from a machine whose clock is behind can be missed. That is why it stays off by default. On this release the large-store stress run (8 writers, kill -9, about 1000 write attempts) kept the commit p95 under the 300 ms target on macOS; see [installation.md](installation.md#8-verification-status). +- The rename rehash narrows the race with a direct editor. It does not close it. +- Approval follows a trusted-host convention. It is not authentication. +- Linux and macOS only. The Obsidian plugin is desktop only. +- Linux was not checked locally. CI runs it on the pull request. The local checks for this release ran on macOS with Node 24.11.0 and Node 26. + +## Release steps (owner) + +1. Push `release/0.5.0` and open a draft pull request into `main` so CI runs on Linux and macOS with Node 24.11 and 26. Wait for green. +2. Fast-forward `main` to `release/0.5.0`. +3. Change the CHANGELOG heading `0.5.0 (not yet tagged)` to `0.5.0 (YYYY-MM-DD)` if you want the date in the tag. +4. Tag `v0.5.0` on that commit and push the tag. `.github/workflows/release.yml` refuses a tag that does not match `package.json` and both manifests, runs the tests, creates the plugin tag `0.5.0` on the same commit and attaches `main.js`, `manifest.json` and `styles.css`. +5. Paste these notes into the GitHub release, without the DRAFT banner. +6. npm publishing (`npm run build:npm`) is a separate step. diff --git a/manifest.json b/manifest.json index f706a40..00dae19 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,7 @@ { "id": "mozak", "name": "mozak", - "version": "0.4.8", + "version": "0.5.0", "minAppVersion": "1.14.4", "description": "Project scopes and plans shared with AI agents, stored as plain files.", "author": "pitfa19", diff --git a/package-lock.json b/package-lock.json index baf4787..961ade3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "mozak-monorepo", - "version": "0.4.8", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "mozak-monorepo", - "version": "0.4.8", + "version": "0.5.0", "workspaces": [ "packages/*" ], @@ -660,9 +660,9 @@ }, "packages/cli": { "name": "@mozak/cli", - "version": "0.4.8", + "version": "0.5.0", "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" }, "bin": { "mozak": "dist/index.js" @@ -673,16 +673,16 @@ }, "packages/core": { "name": "@mozak/core", - "version": "0.4.8", + "version": "0.5.0", "engines": { "node": ">=24.11.0" } }, "packages/mcp": { "name": "@mozak/mcp", - "version": "0.4.8", + "version": "0.5.0", "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" }, "bin": { "mozak-mcp": "dist/index.js" @@ -693,9 +693,9 @@ }, "packages/obsidian": { "name": "@mozak/obsidian", - "version": "0.4.8", + "version": "0.5.0", "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" }, "devDependencies": { "esbuild": "^0.28.0", diff --git a/package.json b/package.json index ccb0c51..0ebb115 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mozak-monorepo", - "version": "0.4.8", + "version": "0.5.0", "private": true, "type": "module", "workspaces": [ @@ -12,6 +12,9 @@ "scripts": { "build": "tsc -b && npm run build:plugin", "build:plugin": "node packages/obsidian/scripts/build.mjs", + "typecheck": "tsc -b", + "lint": "npm run typecheck && node scripts/check-links.mjs", + "loc": "node scripts/count-loc.mjs", "build:npm": "node scripts/build-npm.mjs", "test": "node --import ./scripts/test-git-isolation.mjs --test --experimental-strip-types packages/core/test/*.test.ts packages/cli/test/*.test.ts packages/mcp/test/*.test.ts packages/obsidian/test/*.test.ts", "test:install": "node --import ./scripts/test-git-isolation.mjs --test scripts/test-install.mjs" diff --git a/packages/cli/package.json b/packages/cli/package.json index 1e97a7d..6995d3e 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@mozak/cli", - "version": "0.4.8", + "version": "0.5.0", "type": "module", "main": "dist/index.js", "bin": { @@ -10,6 +10,6 @@ "node": ">=24.11.0" }, "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" } } diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index d19eabf..215e97b 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -5,11 +5,11 @@ import { closeSync, fstatSync, openSync, readSync } from "node:fs"; import { parseArgs } from "node:util"; -import { decideWithFlags, deleteWithFlags, observePayload, observeWithFlags, planShow, executeOperation, loadInventory, MAX_REQUEST_BYTES, scopeForWorkingCopy, gitCommitScope, DomainError, type OperationOutput } from "@mozak/core"; +import { decideWithFlags, deleteWithFlags, observePayload, observeWithFlags, planShow, executeOperation, loadInventory, MAX_REQUEST_BYTES, scopeForWorkingCopy, gitCommitScope, DomainError, focusChange, focusList, renderFocus, type OperationOutput, type ScopeInventory } from "@mozak/core"; import { runningVersion, upgrade } from "./upgrade.js"; import { doctor, renderDoctor } from "./doctor.js"; -const OWNER_ROUTES = new Set(["decide", "init", "repair", "pull", "rename-files", "retitle", "delete"]); +const OWNER_ROUTES = new Set(["decide", "init", "repair", "pull", "rename-files", "retitle", "delete", "annotate", "recover", "prune", "plans-md"]); /** Read routes that may omit --scope: the scope is then found from the current folder's git origin. */ const CWD_SCOPE_ROUTES = new Set(["context", "check", "review show", "plans", "plan show"]); @@ -36,24 +36,35 @@ const ROUTES: Record = { context: { operation: "context", flags: ["config", "scope", "brief", "plan", "json"], requires: ["config"], requestFile: false }, plans: { operation: "plans", - flags: ["config", "scope", "all", "include-rejected", "limit", "continuation", "json"], + flags: ["config", "scope", "all", "include-rejected", "limit", "continuation", "sort", "json"], requires: ["config"], requestFile: false, mode: "scope", }, + graph: { operation: "graph", flags: ["config", "scope", "all", "json"], requires: ["config"], requestFile: false }, + ready: { operation: "ready", flags: ["config", "scope", "all", "json"], requires: ["config"], requestFile: false }, + similar: { operation: "similar", flags: ["config", "scope", "all", "json"], requires: ["config"], requestFile: false }, + locators: { operation: "locators", flags: ["config", "scope", "all", "plan", "include-private", "json"], requires: ["config"], requestFile: false }, + "plans-md": { operation: "plans-md", flags: ["config", "print", "json"], requires: ["config"], requestFile: false }, + annotate: { operation: "annotate", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, + recover: { operation: "recover", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "review show": { operation: "review", flags: ["config", "scope", "plan", "purpose", "outcome", "json"], requires: ["config", "plan"], requestFile: false }, scopes: { operation: "scopes", flags: ["config", "json"], requires: ["config"], requestFile: false }, - sync: { operation: "sync", flags: ["config", "scope", "json"], requires: ["config"], requestFile: false }, + sync: { operation: "sync", flags: ["config", "scope", "local", "json"], requires: ["config"], requestFile: false }, pull: { operation: "pull", flags: ["config", "scope", "into", "json"], requires: ["config", "scope"], requestFile: false }, - check: { operation: "check", flags: ["config", "scope", "json"], requires: ["config"], requestFile: false }, + check: { operation: "check", flags: ["config", "scope", "history", "json"], requires: ["config"], requestFile: false }, operation: { operation: "operation", flags: ["config", "scope", "id", "json"], requires: ["config", "scope", "id"], requestFile: false }, "plan propose": { operation: "propose", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "plan revise": { operation: "revise", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "plan complete": { operation: "complete", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "plan delete": { operation: "delete", flags: ["config", "scope", "request", ...DELETE_FLAGS], requires: ["config", "scope"], requestFile: true }, "plan show": { operation: "plan-show", flags: ["config", "scope", "plan", "json"], requires: ["config", "plan"], requestFile: false }, + "focus list": { operation: "focus-list", flags: ["config", "scope", "json"], requires: ["config"], requestFile: false }, + "focus add": { operation: "focus-add", flags: ["config", "scope", "plan", "json"], requires: ["config", "scope", "plan"], requestFile: false }, + "focus remove": { operation: "focus-remove", flags: ["config", "scope", "plan", "json"], requires: ["config", "scope", "plan"], requestFile: false }, observe: { operation: "observe", flags: ["config", "scope", "request", ...OBSERVE_FLAGS], requires: ["config", "scope"], requestFile: true }, "review decide": { operation: "decide", flags: ["config", "scope", "request", ...DECIDE_FLAGS], requires: ["config", "scope"], requestFile: true }, + "plan prune": { operation: "prune", flags: ["config", "scope", "rejected", "request"], requires: ["config", "scope", "rejected", "request"], requestFile: true }, "discussion save": { operation: "save-discussion", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "spec attach": { operation: "attach-spec", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, "projection repair": { operation: "repair", flags: ["config", "scope", "request"], requires: ["config", "scope", "request"], requestFile: true }, @@ -66,7 +77,7 @@ const ROUTES: Record = { }; const ROUTE_NAMES = Object.keys(ROUTES); -const BOOLEAN_FLAGS = new Set(["json", "include-rejected", "all", "write", "brief", "dry-run", "allow-completed", "commit"]); +const BOOLEAN_FLAGS = new Set(["json", "include-rejected", "all", "write", "brief", "dry-run", "allow-completed", "commit", "rejected", "local", "print", "include-private"]); class UsageError extends Error {} @@ -76,14 +87,24 @@ function usage(): string { " mozak scope init --scope ID --request FILE (owner)", " mozak scope retitle --scope ID --request FILE (owner; change the scope's display title)", " mozak context [--scope ID] [--brief] [--plan ID] [--json]", - " mozak plans [--scope ID | --all] [--include-rejected] [--limit 1..100] [--continuation TOKEN] [--json]", + " mozak plans [--scope ID | --all] [--include-rejected] [--limit 1..100] [--sort deadline] [--continuation TOKEN] [--json]", + " mozak graph (--scope ID | --all) [--json] (cross-plan refs from owner annotations, with resolution)", + " mozak ready (--scope ID | --all) [--json] (open plans whose needs are met, by deadline; blocked and superseded apart)", + " mozak similar (--scope ID | --all) [--json] (similar plans: duplicate, overlap, supersedes-candidate; rejects moved to another scope)", + " mozak locators (--scope ID | --all) [--plan ID] [--include-private] [--json]", + " (where each source and evidence locator points on this machine)", + " mozak plans-md [--print] [--json] (owner; write plans.md with plan titles and states at each repo root; --print only shows it)", + " mozak annotate --scope ID --request FILE (owner; refs and deadlines in mozak.annotations.json)", " mozak scopes [--json] (read-only index of every scope: id, folder, title, plan counts)", - " mozak sync [--scope ID] [--json] (force-refresh remote scopes; reads refresh them after 10 minutes)", + " mozak sync [--scope ID | --local] [--json] (force-refresh remote scopes; reads refresh them after 10 minutes)", + " (a local --scope or --local: fetch, then fast-forward the vault repo under the scope locks)", " mozak pull --scope ID [--into PATH] (owner; clone the code; vault-plans scopes keep plans in the vault)", " mozak review show [--scope ID] --plan ID [--purpose P] [--outcome ID] [--json]", - " mozak check [--scope ID] [--json]", + " mozak check [--scope ID] [--history N] [--json] (--history: hand edits in the last N commits of mozak.json)", " mozak operation --scope ID --id OP [--json]", " mozak plan show [--scope ID] --plan ID [--json] (compact: lifecycle, eligibility, grants, outcomes, spec, next action)", + " mozak focus list [--scope ID] [--json] (the owner's starred plans per scope, from the inventory)", + " mozak focus add|remove --scope ID --plan ID (owner; star or unstar a plan; edits only the inventory's focus list)", " mozak plan propose|revise|complete --scope ID --request FILE", " mozak plan delete --scope ID --plans A,B --owner-ref REF --owner-message-at ISO --reason TEXT [--allow-completed] [--dry-run] [--json]", " (owner; or --request FILE; receipt keeps the record)", @@ -91,11 +112,13 @@ function usage(): string { " [--activity TEXT] [--activity-kind read|run] [--relation supports|challenges] [--classification observed|inferred|unverified]", " [--anchor A] [--version V] [--limitation TEXT] [--dry-run] [--json]", " mozak observe --scope ID --payload FILE [--dry-run] (payload of examples/observe.json; fresh snapshot, retries stale-input; or --request FILE)", + " mozak plan prune --rejected --scope ID --request FILE (owner; remove the listed rejected plans, refs keep resolving)", " mozak discussion save --scope ID --request FILE (agent; advisory checkpoint only)", " mozak spec attach --scope ID --request FILE (agent; descriptor only, no approval)", " mozak review decide --scope ID --plan ID --purpose P [--outcome ID] [--spec SPEC] --owner-ref REF", " --owner-message-at ISO --reason TEXT [--dry-run] [--json] (owner; reads the fresh subject itself; or --request FILE)", " mozak projection repair --scope ID --request FILE (owner)", + " mozak recover --scope ID --request FILE (owner; remove a write lock from another host or a dead local pid)", " mozak render (--scope ID | --all) [--json] (regenerate stale mozak.md only; never mozak.json)", " mozak rename-files (--scope ID | --all) [--json] (owner; rename pre-0.4 MOZAK.json/MOZAK.md to lowercase)", "Maintenance (no --config needed):", @@ -234,6 +257,8 @@ interface HumanRow { paused?: boolean; reason?: string; continuation?: string; + deadline?: string | null; + deadlineStatus?: string; } interface RemoteInfoRow { scope: string; remote: string; ref: string; stale: boolean; lastFetchAt: string | null; error?: string; source: string } function remoteLines(remote: RemoteInfoRow[] | undefined): string[] { @@ -260,6 +285,8 @@ function renderPlansHuman(data: { if (group === "awaiting" && AWAITING_PURPOSE[row.rowKind]) lines.push(` ${AWAITING_PURPOSE[row.rowKind]}`); if (row.outcome) lines.push(` outcome: ${row.outcome}`); if (row.date) lines.push(` date: ${row.date}`); + if (row.deadline) lines.push(` deadline: ${row.deadline} (${row.deadlineStatus})`); + else if (row.deadlineStatus === "candidates") lines.push(" deadline: several dates, owner picks one"); if (row.paused) lines.push(` paused${row.reason ? `: ${row.reason}` : ""}`); else if (row.reason) lines.push(` reason: ${row.reason}`); } @@ -307,11 +334,13 @@ function renderScopesHuman(data: { coverage?: { selected: number; ok: number; fa return `${lines.join("\n")}\n`; } -function renderSyncHuman(data: { remote?: RemoteInfoRow[]; issues?: { code: string; message: string }[] }): string { +interface LocalSyncInfoRow { repo: string | null; scopes: string[]; status: string; from?: string; to?: string; error?: string } +function renderSyncHuman(data: { remote?: RemoteInfoRow[]; local?: LocalSyncInfoRow[]; issues?: { code: string; message: string }[] }): string { const rows = data.remote ?? []; - if (rows.length === 0) return "no remote scopes in the inventory\n"; + const local = (data.local ?? []).map((r) => `local ${r.repo ?? r.scopes.join(", ")}: ${r.status}${r.from && r.to && r.from !== r.to ? ` ${r.from.slice(0, 8)}..${r.to.slice(0, 8)}` : ""}${r.error ? ` (${r.error})` : ""}`); + if (rows.length === 0 && local.length === 0) return "no remote scopes in the inventory\n"; const warn = (data.issues ?? []).filter((i) => i.code === "cache-not-ignored").map((i) => `warning: ${i.message}`); - return `${[...remoteLines(rows), ...warn].join("\n")}\n`; + return `${[...remoteLines(rows), ...local, ...warn].join("\n")}\n`; } function flagForm(inventory: ReturnType, operation: string, v: Record) { @@ -388,6 +417,12 @@ function renderPlanShow(d: Record): string { } function printEnvelope(output: OperationOutput, json: boolean, routeName: string): void { + // plans-md --print without --json shows the files themselves, each under a comment line naming its path. + if (!json && routeName === "plans-md" && Array.isArray(output.data.files) && output.data.files.every((f) => typeof (f as { content?: unknown }).content === "string")) { + const files = output.data.files as { path: string; content: string }[]; + process.stdout.write(files.map((f) => `\n${f.content}`).join("\n")); + return; + } if (!json && routeName === "sync") { process.stdout.write(renderSyncHuman(output.data)); return; @@ -403,6 +438,22 @@ function printEnvelope(output: OperationOutput, json: boolean, routeName: string process.stdout.write(renderPlansHuman(output.data as Parameters[0])); } +/** + * `mozak focus list|add|remove`. The focus list lives in the inventory file, not in plan state, so these routes call + * core's readFocus and setFocus directly instead of the scope operation facade. add and remove are owner routes: + * agents read focus through `focus list` or MCP `mozak_focus` only. + */ +function focusRoute(configPath: string, inventory: ScopeInventory, operation: string, values: Record): number { + const scope = values.scope as string | undefined; + const out = operation === "focus-list" + ? focusList(inventory, { scope }) + : focusChange(configPath, { scope: scope!, plan: values.plan as string, action: operation === "focus-add" ? "add" : "remove" }); + process.stdout.write(operation === "focus-list" && values.json !== true && out.exitCode === 0 + ? renderFocus(out.data.focus as Record) + : `${JSON.stringify(out.data, null, 2)}\n`); + return out.exitCode; +} + /** upgrade and doctor work on the installation, not on scopes, so they have their own flags and no --config rule. */ function maintenance(name: "upgrade" | "doctor", argv: string[]): number { let values: Record; @@ -483,6 +534,7 @@ function run(argv: string[]): number { } const cwdScope = CWD_SCOPE_ROUTES.has(routeName) && values.scope === undefined && values.all === undefined && values.continuation === undefined; + if (route.operation.startsWith("focus-")) return focusRoute(configPath, inventory, route.operation, values); if (cwdScope) { try { values.scope = scopeForWorkingCopy(inventory, process.cwd()).id; @@ -509,6 +561,7 @@ function run(argv: string[]): number { ...(values.scope !== undefined ? { scope: values.scope } : { all: true }), ...(values["include-rejected"] ? { includeRejected: true } : {}), ...(values.limit !== undefined ? { limit: Number(values.limit) } : {}), + ...(values.sort !== undefined ? { sort: values.sort } : {}), }; if (values.limit !== undefined && !/^[0-9]+$/.test(String(values.limit))) { process.stderr.write("limit must be an integer from 1 to 100\n"); @@ -516,8 +569,22 @@ function run(argv: string[]): number { } } else if (route.operation === "scopes") { args = {}; + } else if (route.operation === "graph" || route.operation === "ready" || route.operation === "similar") { + if ((values.scope === undefined) === (values.all === undefined)) { + process.stderr.write(`${route.operation} needs exactly one of --scope or --all\n${usage()}\n`); + return 2; + } + args = values.all ? { all: true } : { scope: values.scope }; + } else if (route.operation === "locators") { + if ((values.scope === undefined) === (values.all === undefined)) { + process.stderr.write(`locators needs exactly one of --scope or --all\n${usage()}\n`); + return 2; + } + args = { ...(values.all ? { all: true } : { scope: values.scope }), ...(values.plan !== undefined ? { plan: values.plan } : {}), ...(values["include-private"] ? { includePrivate: true } : {}) }; + } else if (route.operation === "plans-md") { + args = values.print ? { print: true } : {}; } else if (route.operation === "sync") { - args = values.scope !== undefined ? { scope: values.scope } : {}; + args = { ...(values.scope !== undefined ? { scope: values.scope } : {}), ...(values.local ? { local: true } : {}) }; } else if (route.operation === "render" || route.operation === "rename-files") { if ((values.scope === undefined) === (values.all === undefined)) { process.stderr.write(`${route.operation} needs exactly one of --scope or --all\n${usage()}\n`); @@ -562,8 +629,15 @@ function run(argv: string[]): number { const text = values.json === true ? `${JSON.stringify(out.data, null, 2)}\n` : renderFlagResult(out.data, configPath); process.stdout.write(text); return out.exitCode; + } else if (route.operation === "check") { + if (values.history !== undefined && !/^[0-9]+$/.test(String(values.history))) { + process.stderr.write("history must be an integer from 1 to 500\n"); + return 2; + } + args = { scope: values.scope, ...(values.history !== undefined ? { history: Number(values.history) } : {}) }; } else if (route.requestFile) { - const flagged = Object.keys(values).filter((k) => values[k] !== undefined && !["config", "scope", "request", "json", "commit"].includes(k)); + // `plan prune` requires --rejected next to --request: it names the kind of plan pruned, it is not a payload field. + const flagged = Object.keys(values).filter((k) => values[k] !== undefined && !["config", "scope", "request", "json", "commit", "rejected"].includes(k)); if (flagged.length) { process.stderr.write(`--request cannot be combined with --${flagged[0]}\n`); return 2; @@ -585,7 +659,7 @@ function run(argv: string[]): number { if (route.requestFile && (output.data as Record).committed && !values.commit && !(output.data as Record).remotePush) { process.stderr.write(`note: ${committedLabel(output.data as Record)}\n`); } - printEnvelope(output, values.json === true || (routeName !== "plans" && routeName !== "scopes" && routeName !== "sync"), routeName); + printEnvelope(output, values.json === true || (routeName !== "plans" && routeName !== "scopes" && routeName !== "sync" && routeName !== "plans-md"), routeName); return output.exitCode; } diff --git a/packages/cli/test/annotations-cli.test.ts b/packages/cli/test/annotations-cli.test.ts new file mode 100644 index 0000000..5927114 --- /dev/null +++ b/packages/cli/test/annotations-cli.test.ts @@ -0,0 +1,47 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { existsSync, writeFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { cleanup, NOW, world } from "../../core/test/annotations-fixture.ts"; + +// Real CLI subprocess runs against synthetic temp scopes only. +const cliPath = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "dist", "index.js"); +after(cleanup); + +function cli(args: string[]) { + if (!existsSync(cliPath)) throw new Error(`built CLI missing at ${cliPath}; run "npm run build" first`); + const r = spawnSync(process.execPath, ["--no-warnings", cliPath, ...args], { encoding: "utf8", timeout: 30000 }); + return { code: r.status ?? -1, out: r.stdout, err: r.stderr }; +} + +test("CLI: annotate (owner route), graph, ready and plans --sort deadline on a synthetic scope", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a", { purpose: "Synthetic plan a, due 2099-05-01." }); + w.propose("alpha", "b"); + const request = join(w.base, "annotate.json"); + writeFileSync(request, JSON.stringify({ operationId: "cli-annotate-1", scopeId: "alpha", expectedAnnotations: { exists: false, sha256: null }, ownerRef: "synthetic:cli-owner", ownerMessageAt: NOW, items: [{ kind: "ref", planId: "b", target: "alpha/a", relation: "needs", evidence: "Synthetic: b needs a." }] })); + const annotate = cli(["annotate", "--config", w.config, "--scope", "alpha", "--request", request]); + assert.equal(annotate.code, 0, annotate.out + annotate.err); + assert.equal(JSON.parse(annotate.out).status, "ok"); + const replay = cli(["annotate", "--config", w.config, "--scope", "alpha", "--request", request]); + assert.equal(JSON.parse(replay.out).status, "replayed"); + + const graph = cli(["graph", "--config", w.config, "--scope", "alpha"]); + assert.equal(graph.code, 0); + assert.deepEqual(JSON.parse(graph.out).graph.edges.map((e: { from: string; to: string; relation: string }) => [e.from, e.relation, e.to]), [["alpha/b", "needs", "alpha/a"]]); + + const ready = cli(["ready", "--config", w.config, "--scope", "alpha", "--json"]); + assert.equal(ready.code, 0); + const r = JSON.parse(ready.out).ready; + assert.deepEqual(r.ready.map((x: { planId: string; deadline: string }) => [x.planId, x.deadline]), [["a", "2099-05-01"]]); + assert.deepEqual(r.blocked.map((x: { planId: string }) => x.planId), ["b"]); + + const plans = cli(["plans", "--config", w.config, "--scope", "alpha", "--sort", "deadline"]); + assert.equal(plans.code, 0); + assert.match(plans.out, /deadline: 2099-05-01 \(inferred\)/); + + assert.equal(cli(["graph", "--config", w.config]).code, 2); + assert.equal(cli(["ready", "--config", w.config, "--scope", "alpha", "--all"]).code, 2); +}); diff --git a/packages/cli/test/focus-cli.test.ts b/packages/cli/test/focus-cli.test.ts new file mode 100644 index 0000000..13ac8f3 --- /dev/null +++ b/packages/cli/test/focus-cli.test.ts @@ -0,0 +1,48 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { cleanup, world } from "../../core/test/annotations-fixture.ts"; + +// Real CLI subprocess runs against synthetic temp scopes only. Focus edits only the scratch inventory. +const cliPath = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "dist", "index.js"); +after(cleanup); + +function cli(args: string[]) { + if (!existsSync(cliPath)) throw new Error(`built CLI missing at ${cliPath}; run "npm run build" first`); + const r = spawnSync(process.execPath, ["--no-warnings", cliPath, ...args], { encoding: "utf8", timeout: 30000 }); + return { code: r.status ?? -1, out: r.stdout, err: r.stderr }; +} + +test("CLI: focus add, list and remove on a scratch inventory; mozak.json and mozak.md never change", () => { + const w = world(["alpha", "beta"]); + w.propose("alpha", "a1"); w.propose("beta", "b1"); + const before = w.bytes("alpha"); + const add = cli(["focus", "add", "--config", w.config, "--scope", "alpha", "--plan", "a1"]); + assert.equal(add.code, 0, add.out + add.err); + assert.deepEqual(JSON.parse(add.out), { status: "ok", scope: "alpha", focus: ["a1"], changed: true }); + assert.deepEqual(JSON.parse(readFileSync(w.config, "utf8")).scopes[0].focus, ["a1"]); + const all = cli(["focus", "list", "--config", w.config, "--json"]); + assert.equal(all.code, 0, all.err); + assert.deepEqual(JSON.parse(all.out).focus, { alpha: ["a1"], beta: [] }); + const one = cli(["focus", "list", "--config", w.config, "--scope", "alpha"]); + assert.equal(one.code, 0, one.err); + assert.match(one.out, /^alpha: a1$/m); + assert.doesNotMatch(one.out, /beta/); + const remove = cli(["focus", "remove", "--config", w.config, "--scope", "alpha", "--plan", "a1"]); + assert.equal(remove.code, 0, remove.err); + assert.deepEqual(JSON.parse(remove.out).focus, []); + assert.deepEqual(w.bytes("alpha"), before); +}); + +test("CLI: focus add refuses an unknown plan with exit 2 and needs --scope and --plan", () => { + const w = world(["alpha"]); + w.propose("alpha", "a1"); + const bad = cli(["focus", "add", "--config", w.config, "--scope", "alpha", "--plan", "nope"]); + assert.equal(bad.code, 2); + assert.equal(JSON.parse(bad.out).status, "plan-not-found"); + assert.equal(cli(["focus", "add", "--config", w.config, "--scope", "alpha"]).code, 2); + assert.equal(cli(["focus", "list", "--config", w.config, "--scope", "gamma"]).code, 2); +}); diff --git a/packages/cli/test/s2-cli.test.ts b/packages/cli/test/s2-cli.test.ts new file mode 100644 index 0000000..5a6cff8 --- /dev/null +++ b/packages/cli/test/s2-cli.test.ts @@ -0,0 +1,62 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, writeFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { cleanup, NOW, world } from "../../core/test/annotations-fixture.ts"; +import { readScope } from "../../core/src/index.ts"; + +// Real CLI subprocess runs against synthetic temp scopes only. Never a real inventory. +const cliPath = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "dist", "index.js"); +after(cleanup); + +function cli(args: string[], env: Record = {}) { + if (!existsSync(cliPath)) throw new Error(`built CLI missing at ${cliPath}; run "npm run build" first`); + const r = spawnSync(process.execPath, ["--no-warnings", cliPath, ...args], { encoding: "utf8", timeout: 30000, env: { ...process.env, ...env } }); + return { code: r.status ?? -1, out: r.stdout, err: r.stderr }; +} + +test("CLI: recover is an owner route that needs a request file naming the lock", () => { + const w = world(); + const lock = join(w.entries.alpha.root, ".mozak-write-lock"); + mkdirSync(lock); + writeFileSync(join(lock, "owner.json"), JSON.stringify({ token: "cli-tok", pid: 99, host: "synthetic-other-host", acquiredAt: NOW })); + const check = cli(["check", "--config", w.config, "--scope", "alpha"]); + assert.equal(check.code, 3); + assert.equal(JSON.parse(check.out).issues.find((i: { code: string }) => i.code === "write-lock-stuck").lock.verdict, "other-host"); + assert.equal(cli(["recover", "--config", w.config, "--scope", "alpha"]).code, 2, "the request file is required"); + const request = join(w.base, "recover.json"); + writeFileSync(request, JSON.stringify({ requestId: "cli-recover", scopeId: "alpha", lock: { token: "cli-tok", host: "synthetic-other-host", pid: 99 }, ownerRef: "synthetic:owner", ownerMessageAt: NOW })); + const out = cli(["recover", "--config", w.config, "--scope", "alpha", "--request", request]); + assert.equal(out.code, 0, out.out + out.err); + assert.equal(JSON.parse(out.out).status, "ok"); + assert.equal(existsSync(lock), false); +}); + +test("CLI: plan prune --rejected removes listed rejected plans and requires --rejected", () => { + const w = world(); + w.propose("alpha", "keep"); + w.propose("alpha", "gone", {}, false); + w.reject("alpha", "gone"); + const request = join(w.base, "prune.json"); + writeFileSync(request, JSON.stringify({ operationId: "cli-prune", scopeId: "alpha", expected: readScope(w.entries.alpha).snapshot, planIds: ["gone"], ownerRef: "synthetic:owner", ownerMessageAt: NOW })); + assert.equal(cli(["plan", "prune", "--config", w.config, "--scope", "alpha", "--request", request]).code, 2); + const out = cli(["plan", "prune", "--rejected", "--config", w.config, "--scope", "alpha", "--request", request]); + assert.equal(out.code, 0, out.out + out.err); + assert.deepEqual(JSON.parse(out.out).result, { action: "prune-rejected", ids: ["gone"] }); + assert.deepEqual(readScope(w.entries.alpha).state.plans.map((p) => p.id), ["keep"]); +}); + +test("CLI: check --history validates N; sync of a local scope outside git explains itself", () => { + const w = world(); + assert.equal(cli(["check", "--config", w.config, "--scope", "alpha", "--history", "abc"]).code, 2); + const ok = cli(["check", "--config", w.config, "--scope", "alpha", "--history", "5"]); + assert.equal(ok.code, 0, ok.out + ok.err); + assert.equal(JSON.parse(ok.out).history.available, false); + const sync = cli(["sync", "--config", w.config, "--scope", "alpha"]); + assert.equal(sync.code, 2); + assert.match(sync.out, /local .*not-in-git/); + const json = cli(["sync", "--config", w.config, "--local", "--json"]); + assert.equal(JSON.parse(json.out).local[0].status, "not-in-git"); +}); diff --git a/packages/cli/test/s6-cli.test.ts b/packages/cli/test/s6-cli.test.ts new file mode 100644 index 0000000..5e2d373 --- /dev/null +++ b/packages/cli/test/s6-cli.test.ts @@ -0,0 +1,47 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, writeFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { cleanupS6, s6world } from "../../core/test/s6-fixture.ts"; + +// Real CLI subprocess runs against synthetic temp vaults only. +const cliPath = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "dist", "index.js"); +after(cleanupS6); + +function cli(args: string[]) { + if (!existsSync(cliPath)) throw new Error(`built CLI missing at ${cliPath}; run "npm run build" first`); + const r = spawnSync(process.execPath, ["--no-warnings", cliPath, ...args], { encoding: "utf8", timeout: 30000 }); + return { code: r.status ?? -1, out: r.stdout, err: r.stderr }; +} + +test("CLI: similar, locators and plans-md on synthetic vaults", () => { + const w = s6world({ lab: "vault/research/lab", co: "company" }, { repos: ["vault", "company"] }); + mkdirSync(join(w.base, "vault", "research", "notes"), { recursive: true }); + writeFileSync(join(w.base, "vault", "research", "notes", "plan.md"), "# Lab notes\n\nBody.\n"); + w.propose("lab", "cedar-export", { title: "Cedar export pipeline reports", sources: [{ locator: "research/notes/plan.md" }] }); + w.propose("co", "cedar-copy", { title: "Cedar export pipeline reports" }); + + const similar = cli(["similar", "--config", w.config, "--all"]); + assert.equal(similar.code, 0, similar.err); + const report = JSON.parse(similar.out).similar; + assert.deepEqual(report.pairs.map((p: { label: string; a: { planId: string }; b: { planId: string } }) => [p.label, p.a.planId, p.b.planId]), [["duplicate", "cedar-copy", "cedar-export"]]); + assert.equal(cli(["similar", "--config", w.config]).code, 2, "needs --scope or --all"); + + const loc = cli(["locators", "--config", w.config, "--scope", "lab"]); + assert.equal(loc.code, 0, loc.err); + const data = JSON.parse(loc.out); + assert.deepEqual(data.counts, { resolved: 1 }); + assert.equal(data.locators[0].title, "Lab notes"); + + const printed = cli(["plans-md", "--config", w.config, "--print"]); + assert.equal(printed.code, 0, printed.err); + assert.match(printed.out, /\n|${e.relation}| ${safe(e.to)}`); - } - return out.join("\n"); -} diff --git a/packages/core/src/history.ts b/packages/core/src/history.ts new file mode 100644 index 0000000..32fff6c --- /dev/null +++ b/packages/core/src/history.ts @@ -0,0 +1,59 @@ +// S2 `check --history N`: find hand edits of mozak.json in git history. Every mozak write sets a new +// storage.revision and records it in a receipt, so a commit that changed mozak.json while keeping the revision, +// or that introduced a revision no receipt names, was made by hand. Reads local git objects only, no network. + +import { execFileSync } from "node:child_process"; +import { scopeFileName } from "./scope-files.ts"; + +export const MAX_HISTORY = 500; + +export interface HistoryFinding { code: "hand-edit" | "hand-edit-revision" | "history-invalid-json"; message: string; commit: string; date: string; removedPlans?: string[]; addedPlans?: string[] } +export interface HistoryReport { available: boolean; scanned: number; findings: HistoryFinding[]; reason?: string } + +function git(root: string, args: string[]): string | null { + try { + return execFileSync("git", args, { cwd: root, encoding: "utf8", timeout: 20_000, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"], env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" } }); + } catch { return null; } +} + +interface Parsed { revision: string | null; planIds: string[]; receiptRevisions: Set } +function parse(bytes: string): Parsed | null { + try { + const raw = JSON.parse(bytes) as { storage?: { revision?: unknown }; plans?: { id?: unknown }[]; receipts?: Record }; + const revision = typeof raw.storage?.revision === "string" ? raw.storage.revision : null; + const planIds = Array.isArray(raw.plans) ? raw.plans.map((p) => (typeof p?.id === "string" ? p.id : "")).filter(Boolean) : []; + const receiptRevisions = new Set(Object.values(raw.receipts ?? {}).map((r) => r?.storageRevision).filter((v): v is string => typeof v === "string")); + return { revision, planIds, receiptRevisions }; + } catch { return null; } +} + +/** Walk the last `limit` commits that touched this scope's mozak.json, newest first. */ +export function handEditHistory(root: string, limit: number): HistoryReport { + if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY) throw new RangeError(`history must be an integer from 1 to ${MAX_HISTORY}`); + if (git(root, ["rev-parse", "--is-inside-work-tree"])?.trim() !== "true") return { available: false, scanned: 0, findings: [], reason: "the scope folder is not in a git repository" }; + const name = scopeFileName(root, "graph"); + const log = git(root, ["log", "-n", String(limit), "--format=%H %cI", "--", name]); + if (log === null) return { available: false, scanned: 0, findings: [], reason: "git log failed" }; + const commits = log.split("\n").filter(Boolean).map((l) => { const [sha, date] = l.split(" "); return { sha: sha!, date: date ?? "" }; }); + const findings: HistoryFinding[] = []; + for (const c of commits) { + const short = c.sha.slice(0, 10); + const after = git(root, ["show", `${c.sha}:./${name}`]); + if (after === null) continue; // deleted in this commit + const next = parse(after); + if (!next) { findings.push({ code: "history-invalid-json", message: `commit ${short} left ${name} as invalid JSON`, commit: c.sha, date: c.date }); continue; } + const before = git(root, ["show", `${c.sha}^:./${name}`]); + const prev = before === null ? null : parse(before); + if (before !== null && prev && before !== after && prev.revision !== null && prev.revision === next.revision) { + const removedPlans = prev.planIds.filter((id) => !next.planIds.includes(id)); + const addedPlans = next.planIds.filter((id) => !prev.planIds.includes(id)); + const what = [removedPlans.length ? `removed plans ${removedPlans.join(", ")}` : "", addedPlans.length ? `added plans ${addedPlans.join(", ")}` : ""].filter(Boolean).join("; "); + findings.push({ code: "hand-edit", message: `commit ${short} changed ${name} but kept storage.revision${what ? ` (${what})` : ""}; refs and snapshots may point at removed content`, commit: c.sha, date: c.date, ...(removedPlans.length ? { removedPlans } : {}), ...(addedPlans.length ? { addedPlans } : {}) }); + continue; + } + if (next.revision !== null && next.receiptRevisions.size > 0 && !next.receiptRevisions.has(next.revision) && (prev === null || prev.revision !== next.revision)) { + findings.push({ code: "hand-edit-revision", message: `commit ${short} set storage.revision to a value no receipt records; mozak did not write it`, commit: c.sha, date: c.date }); + } + } + return { available: true, scanned: commits.length, findings }; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index b5cd168..6b3b3fa 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -1,11 +1,7 @@ -// Read-only legacy inspection and pure parsers, not current scope authority. -export * from "./parse.ts"; -export * from "./check.ts"; -export * from "./graph.ts"; -export * from "./translate.ts"; -export * from "./stale.ts"; -export { auditProject, mozakTemplate } from "./init.ts"; -export { hashText, readSnapshot, EMPTY_HASH } from "./write.ts"; +// Read-only note helpers and text folding. +export * from "./notes.ts"; +export * from "./fold.ts"; +export * from "./paths.ts"; // Supported v3 understanding model, conversation and guarded public operations. export * from "./errors.ts"; @@ -16,6 +12,7 @@ export * from "./scope-files.ts"; export * from "./scope-list.ts"; export * from "./review.ts"; export * from "./delete.ts"; +export * from "./focus.ts"; export * from "./roadmap.ts"; export { mdText, stopLabel, completedPlanLine, planHeading, planDisplayState, progressStrip, type PlanDisplayState } from "./bridge.ts"; export * from "./api.ts"; @@ -26,5 +23,17 @@ export * from "./visibility.ts"; export * from "./working-copy.ts"; export * from "./durable.ts"; export * from "./update.ts"; +export * from "./annotations.ts"; +export * from "./deadlines.ts"; +export * from "./crossplan.ts"; +export * from "./settings.ts"; +export * from "./lock-recover.ts"; +export * from "./prune.ts"; +export * from "./history.ts"; +export * from "./local-sync.ts"; +export * from "./locators.ts"; +export * from "./similar.ts"; +export * from "./plans-index.ts"; + export * from "./vault-config.ts"; export * from "./git-commit.ts"; diff --git a/packages/core/src/init.ts b/packages/core/src/init.ts deleted file mode 100644 index 9a417b3..0000000 --- a/packages/core/src/init.ts +++ /dev/null @@ -1,107 +0,0 @@ -import { existsSync, readdirSync, readFileSync, lstatSync, type Dirent } from "node:fs"; -import { basename, join, resolve } from "node:path"; -import { DomainError } from "./errors.ts"; - -export interface InitOptions { - id?: string; - kind: "project" | "topic"; - title?: string; -} - -export interface InitResult { - created: string[]; - skipped: string[]; -} - -const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "scope"; - -export function mozakTemplate(id: string, kind: "project" | "topic", plan = "- [ ] first step"): string { - return `---\nid: ${id}\nkind: ${kind}\nformat: 1\n---\n\n## Plan\n\n${plan}\n\n## Links\n\n## Translations\n`; -} - -/** Format-1 scaffolding is retired, including its old free-edit instructions. */ -export function initScope(_dir: string, _opts: InitOptions): never { - throw new DomainError("unsupported-legacy-operation", "format-1 init is retired; explicitly initialize a new inventoried format-2 scope"); -} - -export interface AuditReport { - dir: string; - hasOldState: boolean; - /** Old project id, if project.yml named one. */ - oldId: string | null; - /** First line of the old idea.md intent, if present. */ - intent: string | null; - openQuestions: string[]; - counts: Record; - /** Suggested mozak.md text. The owner edits it and approves. Nothing is written. */ - draft: string; - notes: string[]; -} - -function countFiles(dir: string): number { - let n = 0; - const walk = (d: string) => { - let entries: Dirent[]; - try { - entries = readdirSync(d, { withFileTypes: true }); - } catch { - return; // unreadable directory, leave it uncounted rather than crash - } - for (const e of entries) { - // Dirent does not follow symlinks, so a dangling link (left by browser profiles) cannot throw. - if (e.isDirectory()) walk(join(d, e.name)); - else n++; - } - }; - walk(dir); - return n; -} - -function section(md: string, heading: string): string { - const m = new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s|(?![\\s\\S]))`, "mi").exec(md); - return m ? m[1].trim() : ""; -} - -/** Read only. Look at an old .mozak/ directory and propose a mozak.md draft. Never writes, never deletes. */ -export function auditProject(dir: string, kind: "project" | "topic" = "project"): AuditReport { - const root = resolve(dir); - const old = join(root, ".mozak"); - const notes: string[] = []; - const counts: Record = {}; - if (!existsSync(old)) { - return { dir: root, hasOldState: false, oldId: null, intent: null, openQuestions: [], counts, draft: mozakTemplate(slug(basename(root)), kind), notes: ["no .mozak/ directory, nothing to port"] }; - } - for (const name of readdirSync(old)) { - const p = join(old, name); - counts[name] = lstatSync(p).isDirectory() ? countFiles(p) : 1; - } - let oldId: string | null = null; - const yml = join(old, "project.yml"); - if (existsSync(yml)) { - const m = /^\s*id:\s*(\S+)/m.exec(readFileSync(yml, "utf8")); - oldId = m ? m[1] : null; - } - let intent: string | null = null; - let openQuestions: string[] = []; - const idea = join(old, "idea.md"); - if (existsSync(idea)) { - const md = readFileSync(idea, "utf8"); - intent = section(md, "Intent") || null; - openQuestions = section(md, "Open questions").split(/\r?\n/).map((l) => l.replace(/^[-*]\s+/, "").trim()).filter(Boolean); - } else notes.push("no idea.md, so there is no intent to carry over"); - - const planPieces: string[] = []; - if (intent) planPieces.push(`Intent: ${intent}`); - for (const q of openQuestions) planPieces.push(`- [ ] ${q}`); - if (planPieces.length === 0) planPieces.push("- [ ] first step"); - - const features = counts["features"] ?? 0; - const planning = counts["planning"] ?? 0; - if (features) notes.push(`${features} feature files exist. Finished work belongs in git history, so none are carried into the plan. Review them by hand for open items.`); - if (planning) notes.push(`${planning} planning files exist. Look for goals that are not completed and add only those to the plan.`); - if (counts["evidence"]) notes.push(`${counts["evidence"]} evidence files exist. Evidence becomes plain notes in a topic, linked from Links.`); - if (counts["concepts"] || counts["translations"]) notes.push("old concepts or translations exist. Re-create them as Translations blocks only if still wanted, with every assumption re-derived."); - notes.push("archive .mozak/ only after you have reviewed this draft and approved it"); - - return { dir: root, hasOldState: true, oldId, intent, openQuestions, counts, draft: mozakTemplate(oldId ?? slug(basename(root)), kind, planPieces.join("\n")), notes }; -} diff --git a/packages/core/src/local-sync.ts b/packages/core/src/local-sync.ts new file mode 100644 index 0000000..843b4a6 --- /dev/null +++ b/packages/core/src/local-sync.ts @@ -0,0 +1,86 @@ +// S2 `mozak sync` for local scopes inside a git repo (a vault). Replaces a bare `git pull --rebase`, which bypasses +// the scope locks. Per repo: fetch outside the locks, take the write locks of every inventoried scope in that repo in +// path order, `git merge --ff-only` the upstream, release. A diverged history is never merged or rebased: the sync +// stops and reports it, so the owner decides. Nothing here pushes. + +import { execFileSync } from "node:child_process"; +import { DomainError } from "./errors.ts"; +import { isWithin, realOrSelf } from "./paths.ts"; +import { withScopeLocks, type StoreOptions } from "./scope-store.ts"; +import type { ScopeEntry } from "./scope-index.ts"; + +const FETCH_TIMEOUT_MS = 60_000; + +export type LocalSyncStatus = "fast-forwarded" | "up-to-date" | "ahead" | "not-fast-forward" | "fetch-failed" | "busy" | "merge-failed" | "no-upstream" | "detached" | "not-in-git"; +export const LOCAL_SYNC_OK: ReadonlySet = new Set(["fast-forwarded", "up-to-date", "ahead"]); +export interface LocalSyncRow { repo: string | null; scopes: string[]; locked: string[]; status: LocalSyncStatus; upstream?: string; from?: string; to?: string; error?: string } + +class GitError extends Error {} +function git(cwd: string, args: string[], timeout = 20_000): string { + try { + return execFileSync("git", args, { cwd, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "", LC_ALL: "C" } }).trim(); + } catch (err) { + const e = err as { stderr?: Buffer | string; killed?: boolean; code?: string; message?: string }; + const stderr = String(e.stderr ?? "").trim().split("\n").slice(-2).join(" "); + throw new GitError(e.killed || e.code === "ETIMEDOUT" ? `git ${args[0]} timed out` : `git ${args[0]}: ${stderr || e.message || "failed"}`); + } +} +function tryGit(cwd: string, args: string[]): string | null { try { return git(cwd, args); } catch { return null; } } + +/** Scopes whose plan files live in a local folder: local scopes and vault-plans scopes. Repo-mode remotes have their own sync. */ +export function localEntries(scopes: ScopeEntry[]): ScopeEntry[] { + return scopes.filter((s) => !s.remote || s.remote.plansMode === "vault"); +} + +/** + * Sync the git repos that hold `targets`. Every inventoried local or vault-plans scope inside such a repo is locked + * during the merge, not only the targets, because the merge rewrites the whole working tree. + */ +export function syncLocal(targets: ScopeEntry[], all: ScopeEntry[], options: StoreOptions = {}): LocalSyncRow[] { + const candidates = localEntries(all); + const repos = new Map(); + const rows: LocalSyncRow[] = []; + for (const entry of localEntries(targets)) { + const top = tryGit(entry.root, ["rev-parse", "--show-toplevel"]); + if (!top) { rows.push({ repo: null, scopes: [entry.id], locked: [], status: "not-in-git" }); continue; } + const key = realOrSelf(top); + repos.set(key, [...(repos.get(key) ?? []), entry]); + } + for (const [top, selected] of repos) { + const scopes = selected.map((e) => e.id).sort(); + const lockRoots = candidates.filter((e) => isWithin(realOrSelf(e.root), top)); + const locked = lockRoots.map((e) => e.id).sort(); + const row = (status: LocalSyncStatus, extra: Partial = {}): LocalSyncRow => ({ repo: top, scopes, locked, status, ...extra }); + const branch = tryGit(top, ["symbolic-ref", "--short", "-q", "HEAD"]); + if (!branch) { rows.push(row("detached")); continue; } + const remote = tryGit(top, ["config", "--get", `branch.${branch}.remote`]); + const upstream = tryGit(top, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]); + if (!remote || !upstream) { rows.push(row("no-upstream")); continue; } + // Fetch outside the locks: it can take seconds and only updates remote-tracking refs. + try { git(top, ["fetch", "--quiet", "--", remote], FETCH_TIMEOUT_MS); } + catch (e) { rows.push(row("fetch-failed", { upstream, error: (e as Error).message })); continue; } + const head = git(top, ["rev-parse", "HEAD"]); + const up = git(top, ["rev-parse", "@{u}"]); + if (head === up) { rows.push(row("up-to-date", { upstream, from: head, to: head })); continue; } + const behind = tryGit(top, ["merge-base", "--is-ancestor", "HEAD", "@{u}"]) !== null; + if (!behind) { + const ahead = tryGit(top, ["merge-base", "--is-ancestor", "@{u}", "HEAD"]) !== null; + rows.push(row(ahead ? "ahead" : "not-fast-forward", { upstream, from: head, to: head, ...(ahead ? {} : { error: "local and upstream history diverged; nothing was merged" }) })); + continue; + } + try { + const after = withScopeLocks(lockRoots.map((e) => e.root), () => { + options.onPhase?.("sync-locked"); + // ff-only refuses anything but a fast-forward, and refuses before touching files a local change would lose. + git(top, ["merge", "--ff-only", "--quiet", up]); + return git(top, ["rev-parse", "HEAD"]); + }, options); + rows.push(row("fast-forwarded", { upstream, from: head, to: after })); + } catch (e) { + if (e instanceof DomainError && (e.code === "busy" || e.code === "recovery-required")) rows.push(row("busy", { upstream, from: head, to: head, error: e.message })); + else if (e instanceof GitError) rows.push(row("merge-failed", { upstream, from: head, to: tryGit(top, ["rev-parse", "HEAD"]) ?? head, error: e.message })); + else throw e; + } + } + return rows; +} diff --git a/packages/core/src/locators.ts b/packages/core/src/locators.ts new file mode 100644 index 0000000..bd6f539 --- /dev/null +++ b/packages/core/src/locators.ts @@ -0,0 +1,344 @@ +// Locator resolution (D3 goal 3, "built regardless"): where does a plan's Source.locator or Evidence.locator point +// on this machine? Read only. No model, no stored index: the note index is built per call from the index roots. +// +// Index roots come from `indexRoots` in mozak-settings.json. Without that key they are derived from the inventory: +// the top-level folder of each git repo that holds a local scope, with a folder named "personal" private, and no +// root for a scope that is itself a repo root (a company vault is not searched by default). +// A private root returns path and title only, unless the call sets includePrivate (the usage log records that). + +import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs"; +import { homedir } from "node:os"; +import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path"; +import { foldKey } from "./fold.ts"; +import { commitTimes, dirtyPaths, findRepoRoot, noteIndex, noteKey, touched, wikiLinks, type NoteIndex } from "./notes.ts"; +import { realOrSelf } from "./paths.ts"; +import type { ScopeEntry, ScopeInventory } from "./scope-index.ts"; +import { scopeFileName } from "./scope-files.ts"; +import { loadSettings, type IndexRoot } from "./settings.ts"; +import type { Plan, ScopeState } from "./understanding.ts"; + +export interface LocatorRoot extends IndexRoot { source: "setting" | "default" } + +export type LocatorKind = "url" | "git" | "path" | "wikilink" | "text"; +export type LocatorStatus = + /** A URL or git object: not checked on disk. */ + | "external" + /** One file or folder found. */ + | "resolved" + /** Looks like a path or note link, nothing found. */ + | "missing" + /** A note link with several matching notes and none in the citing scope. */ + | "ambiguous" + /** A relative path in a scope whose code lives in a remote repo that is not cloned here. */ + | "remote" + /** Prose (an owner message, a command): nothing to resolve. */ + | "not-checked"; + +export interface LocatorResolution { + kind: LocatorKind; + status: LocatorStatus; + /** Absolute path, when resolved. */ + path?: string; + /** First heading, front matter title, or the file name. */ + title?: string; + /** Inside a private index root. Only path and title are returned then. */ + private?: boolean; + /** For a resolved Markdown note with an anchor: whether a heading matches it. null when not judged. */ + anchorFound?: boolean | null; + /** Up to 200 characters of the anchored section or the note body. Never for private or unindexed files. */ + excerpt?: string; + /** Paths of every matching note, for ambiguous note links. */ + candidates?: string[]; +} + +const URL_RE = /^[a-z][a-z0-9+.-]*:\/\//i; +const GIT_RE = /^git:/i; +const EXT_RE = /\.[A-Za-z0-9]{1,8}$/; +const READ_LIMIT = 64 * 1024; + +const inside = (path: string, dir: string) => path === dir || path.startsWith(dir.endsWith(sep) ? dir : dir + sep); + +/** Default roots: see the header comment. Deterministic, file-system only. */ +export function defaultIndexRoots(inv: ScopeInventory): LocatorRoot[] { + const out = new Map(); + for (const entry of inv.scopes) { + if (entry.remote && entry.remote.plansMode === "repo") continue; + const root = realOrSelf(entry.root); + const repo = findRepoRoot(root); + if (!repo || repo === root) continue; + const top = relative(repo, root).split(sep)[0]; + if (!top || top.startsWith("..")) continue; + const path = join(repo, top); + if (!out.has(path)) out.set(path, { path, private: foldKey(top) === "personal", source: "default" }); + } + return [...out.values()].sort((a, b) => a.path.localeCompare(b.path)); +} + +export function indexRootsFor(inv: ScopeInventory): LocatorRoot[] { + const configured = loadSettings(inv).indexRoots; + if (configured) return configured.map((r) => ({ ...r, source: "setting" as const })); + return defaultIndexRoots(inv); +} + +/** Resolution context for one inventory: roots, plus a note index built once on first use. */ +export class LocatorResolver { + readonly roots: LocatorRoot[]; + readonly includePrivate: boolean; + private notes: NoteIndex | null = null; + private extraNotes = new Map(); + private titles = new Map(); + + constructor(inv: ScopeInventory, opts: { includePrivate?: boolean; roots?: LocatorRoot[] } = {}) { + this.roots = opts.roots ?? indexRootsFor(inv); + this.includePrivate = opts.includePrivate === true; + } + + private noteIndexFor(scopeRoot: string): NoteIndex { + if (!this.notes) this.notes = noteIndex(this.roots.map((r) => r.path)); + if (this.roots.some((r) => inside(scopeRoot, r.path))) return this.notes; + // The citing scope is outside every root (a company vault): its own notes are searched too, for its own links. + if (!this.extraNotes.has(scopeRoot)) { + const merged: NoteIndex = new Map([...this.notes].map(([k, v]) => [k, [...v]])); + for (const [k, v] of noteIndex([scopeRoot])) merged.set(k, [...(merged.get(k) ?? []), ...v.filter((p) => !(merged.get(k) ?? []).includes(p))]); + this.extraNotes.set(scopeRoot, merged); + } + return this.extraNotes.get(scopeRoot)!; + } + + private rootOf(path: string): LocatorRoot | null { + let best: LocatorRoot | null = null; + for (const r of this.roots) if (inside(path, r.path) && (!best || r.path.length > best.path.length)) best = r; + return best; + } + + private read(path: string): { title: string; text: string | null } { + const hit = this.titles.get(path); + if (hit) return hit; + let text: string | null = null; + let title = basename(path); + try { + if (statSync(path).isFile() && /\.md$/i.test(path)) { + const fd = openSync(path, "r"); + try { + const buf = Buffer.alloc(READ_LIMIT); + const n = readSync(fd, buf, 0, READ_LIMIT, 0); + const body = buf.subarray(0, n).toString("utf8"); + text = body; + title = noteTitle(body) ?? basename(path, extname(path)); + } finally { closeSync(fd); } + } + } catch { /* unreadable: title stays the file name */ } + const out = { title, text }; + this.titles.set(path, out); + return out; + } + + private found(path: string, anchor: string | null, scopeRoot: string, kind: LocatorKind): LocatorResolution { + const root = this.rootOf(path); + const isPrivate = root?.private === true; + const indexed = root !== null || inside(path, scopeRoot); + const { title, text } = this.read(path); + const out: LocatorResolution = { kind, status: "resolved", path, title }; + if (isPrivate) out.private = true; + const detail = this.includePrivate || (indexed && !isPrivate); + if (text !== null) { + const section = anchor ? anchoredSection(text, anchor) : null; + out.anchorFound = anchor ? section !== null : null; + if (detail) { + const ex = excerptOf(section ?? stripFrontMatter(text)); + if (ex) out.excerpt = ex; + } + } else out.anchorFound = null; + return out; + } + + /** Resolve one locator cited from a scope. Never throws for odd input. */ + resolve(entry: ScopeEntry, locator: string, anchor: string | null = null): LocatorResolution { + const raw = locator.trim(); + if (!raw) return { kind: "text", status: "not-checked" }; + if (URL_RE.test(raw)) return { kind: "url", status: "external" }; + if (GIT_RE.test(raw)) return { kind: "git", status: "external" }; + const scopeRoot = realOrSelf(entry.root); + const link = raw.includes("[[") ? wikiLinks(raw)[0] : undefined; + if (link) return this.resolveNote(scopeRoot, link.target, link.anchor ?? anchor); + + let path = raw; + let inlineAnchor: string | null = null; + const hash = raw.indexOf("#"); + if (hash > 0) { inlineAnchor = raw.slice(hash + 1).trim() || null; path = raw.slice(0, hash); } + path = path.replace(/:\d+(?:-\d+)?$/, ""); + const anchorUsed = inlineAnchor ?? anchor; + const explicit = path.startsWith("/") || path.startsWith("~/") || path === "~" || path.startsWith("./") || path.startsWith("../"); + const pathLike = explicit || (!/['"`;,]|\s{2}/.test(path) && /^[^\s:]+(?: [^\s:]+){0,6}$/.test(path) && (path.includes("/") || EXT_RE.test(path))); + if (!pathLike) return { kind: "text", status: "not-checked" }; + + for (const candidate of this.candidates(entry, scopeRoot, path)) { + if (existsSync(candidate)) return this.found(realOrSelf(candidate), anchorUsed, scopeRoot, "path"); + } + // A bare note name with .md may be a note anywhere in the roots, as Obsidian would find it. + if (!path.includes("/") && /\.md$/i.test(path)) { + const note = this.resolveNote(scopeRoot, path, anchorUsed); + if (note.status !== "missing") return { ...note, kind: "path" }; + } + if (!explicit && entry.remote && !entry.remote.fullClone) return { kind: "path", status: "remote" }; + return { kind: "path", status: "missing" }; + } + + private candidates(entry: ScopeEntry, scopeRoot: string, path: string): string[] { + if (path === "~" || path.startsWith("~/")) return [join(homedir(), path.slice(1))]; + if (isAbsolute(path)) return [path]; + const bases = [scopeRoot]; + const repo = findRepoRoot(scopeRoot); + if (repo) bases.push(repo); + if (entry.remote?.fullClone) bases.push(entry.remote.fullClone); + for (const r of this.roots) bases.push(dirname(r.path), r.path); + return [...new Set(bases.map((b) => resolve(b, path)))]; + } + + private resolveNote(scopeRoot: string, target: string, anchor: string | null): LocatorResolution { + const idx = this.noteIndexFor(scopeRoot); + const name = target.split("/").pop() ?? target; + let hits = idx.get(noteKey(name)) ?? []; + if (target.includes("/")) { + const suffix = foldKey(target.replace(/\.md$/i, "")) + ".md"; + hits = hits.filter((p) => foldKey(p).endsWith(suffix)); + } + if (hits.length === 0) return { kind: "wikilink", status: "missing" }; + const local = hits.filter((p) => inside(realOrSelf(p), scopeRoot)); + const pick = hits.length === 1 ? hits[0] : local.length === 1 ? local[0] : null; + if (!pick) return { kind: "wikilink", status: "ambiguous", candidates: hits.map((p) => realOrSelf(p)).filter((p) => this.includePrivate || !this.rootOf(p)?.private).sort() }; + return this.found(realOrSelf(pick), anchor, scopeRoot, "wikilink"); + } +} + +function stripFrontMatter(text: string): string { + if (!text.startsWith("---\n")) return text; + const end = text.indexOf("\n---", 4); + return end < 0 ? text : text.slice(end + 4); +} + +/** First H1, else front matter title, else null. */ +export function noteTitle(text: string): string | null { + const fm = text.startsWith("---\n") ? text.slice(4, Math.max(4, text.indexOf("\n---", 4))) : ""; + const body = stripFrontMatter(text); + const h1 = /^# +(.+?)\s*#*\s*$/m.exec(body.split("\n").slice(0, 60).join("\n")); + if (h1) return h1[1].trim(); + const t = /^title:\s*["']?(.+?)["']?\s*$/m.exec(fm); + return t ? t[1].trim() : null; +} + +const headingKey = (s: string) => foldKey(s).replace(/[^\p{L}\p{N}]+/gu, " ").trim(); + +/** Text under the first heading that matches the anchor (equal, or one contains the other), else null. */ +export function anchoredSection(text: string, anchor: string): string | null { + const want = headingKey(anchor.replace(/^#+/, "")); + if (!want) return null; + const lines = text.split("\n"); + let fence = false; + for (let i = 0; i < lines.length; i++) { + if (/^\s{0,3}(```|~~~)/.test(lines[i])) { fence = !fence; continue; } + if (fence) continue; + const m = /^(#{1,6}) +(.+?)\s*#*\s*$/.exec(lines[i]); + if (!m) continue; + const have = headingKey(m[2]); + if (!have || !(have === want || have.includes(want) || want.includes(have))) continue; + const level = m[1].length; + const body: string[] = []; + for (let j = i + 1; j < lines.length; j++) { + const h = /^(#{1,6}) /.exec(lines[j]); + if (h && h[1].length <= level) break; + body.push(lines[j]); + } + return body.join("\n"); + } + return null; +} + +function excerptOf(text: string): string | undefined { + const line = text.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#") && !/^(```|~~~|---)/.test(l)); + if (!line) return undefined; + return line.length > 200 ? `${line.slice(0, 199)}…` : line; +} + +/** Every locator a plan cites: content sources (accepted and pending) and observation evidence. */ +export interface Citation { + planId: string; + field: "source" | "evidence"; + id: string; + locator: string; + anchor: string | null; + /** observedAt for a source, inspectedAt for evidence. */ + citedAt: string; +} + +export function planCitations(plan: Plan): Citation[] { + const out: Citation[] = []; + const seen = new Set(); + for (const rev of [plan.accepted, plan.pending]) { + for (const s of rev?.content.sources ?? []) { + const k = `source\0${s.id}\0${s.locator}`; + if (seen.has(k)) continue; + seen.add(k); + out.push({ planId: plan.id, field: "source", id: s.id, locator: s.locator, anchor: s.anchor, citedAt: s.observedAt }); + } + } + for (const o of plan.observations) for (const e of o.evidence) out.push({ planId: plan.id, field: "evidence", id: e.id, locator: e.locator, anchor: e.anchor, citedAt: e.inspectedAt }); + return out; +} + +const live = (p: Plan) => p.lifecycle.state !== "completed" && !(p.lifecycle.state === "unaccepted" && p.pending?.reviewState === "rejected"); + +export interface CitedNoteChange { + code: "cited-note-changed"; + message: string; + planId: string; + path: string; + citedAt: string; + changedAt: string; + source: "commit" | "uncommitted"; +} + +/** + * Cited-note staleness for `check`: a file a live plan cites (source or evidence) that changed after the latest + * citation. Time comes from git (touched()). A citation counts from the first commit of this scope's mozak.json at or + * after its citedAt, so a note committed while the citation itself was still uncommitted is not reported. Files + * outside git are not judged. Informational only: a change does not mean the edit matters. + */ +export function citedNoteChanges(inv: ScopeInventory, entry: ScopeEntry, state: ScopeState, resolver = new LocatorResolver(inv)): CitedNoteChange[] { + const latest = new Map(); + for (const plan of state.plans) { + if (!live(plan)) continue; + for (const c of planCitations(plan)) { + const r = resolver.resolve(entry, c.locator, c.anchor); + if (r.status !== "resolved" || !r.path) continue; + const key = `${plan.id}\0${r.path}`; + const prev = latest.get(key); + if (!prev || Date.parse(c.citedAt) > Date.parse(prev.citedAt)) latest.set(key, { planId: plan.id, path: r.path, citedAt: c.citedAt }); + } + } + if (latest.size === 0) return []; + const graph = join(realOrSelf(entry.root), scopeFileName(entry.root, "graph")); + const ownRepo = findRepoRoot(entry.root); + const recorded = ownRepo ? commitTimes(ownRepo, graph) : []; + /** When a citation landed: the first mozak.json commit at or after citedAt, else citedAt itself. */ + const landed = (cited: number) => recorded.find((t) => t >= cited) ?? cited; + const dirtyByRepo = new Map(); + const out: CitedNoteChange[] = []; + for (const { planId, path, citedAt } of latest.values()) { + const repo = findRepoRoot(path); + if (!repo) continue; + if (!dirtyByRepo.has(repo)) dirtyByRepo.set(repo, dirtyPaths(repo)); + const t = touched(path, { root: repo, paths: dirtyByRepo.get(repo)! }); + const cited = Math.floor(Date.parse(citedAt) / 1000); + if (t.epoch === null || t.source === "none" || !Number.isFinite(cited)) continue; + if (t.epoch <= (t.source === "commit" ? landed(cited) : cited)) continue; + const changedAt = new Date(t.epoch * 1000).toISOString(); + const shown = relative(repo, path) || path; + out.push({ + code: "cited-note-changed", + message: `plan ${planId} cites ${shown}, which changed ${changedAt.slice(0, 10)}${t.source === "uncommitted" ? " (uncommitted)" : ""} after it was cited ${citedAt.slice(0, 10)}. Changed does not mean the edit matters.`, + planId, path, citedAt, changedAt, source: t.source, + }); + } + return out.sort((a, b) => a.planId.localeCompare(b.planId) || a.path.localeCompare(b.path)); +} diff --git a/packages/core/src/lock-recover.ts b/packages/core/src/lock-recover.ts new file mode 100644 index 0000000..62f4a71 --- /dev/null +++ b/packages/core/src/lock-recover.ts @@ -0,0 +1,133 @@ +// Write-lock inspection and owner recovery (S2). A lock is never stolen because it is old. The owner route +// `recover` removes one named lock only when its owner cannot still be writing on this machine: the lock names +// another host (it can only have arrived by sync), or it names this host and a pid that is no longer running. + +import { randomUUID } from "node:crypto"; +import { hostname } from "node:os"; +import { lstatSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync } from "node:fs"; +import { join } from "node:path"; +import { DomainError } from "./errors.ts"; +import { fsyncDir } from "./durable.ts"; +import { WRITE_LOCK_DIR } from "./scope-index.ts"; +import { MAX_REQUEST_BYTES, canonical } from "./understanding.ts"; + +export type LockVerdict = "absent" | "other-host" | "dead-local-pid" | "live-local-pid" | "host-unknown" | "metadata-unavailable"; +export interface LockInfo { + present: boolean; + token: string | null; + host: string | null; + pid: number | null; + acquiredAt: string | null; + /** Entries in the lock folder other than owner.json. A lock with extra entries is never removed. */ + extraEntries: string[]; + verdict: LockVerdict; +} +/** Testing seams. Never accepted from CLI or MCP input. */ +export interface LockProbe { hostname?: () => string; isAlive?: (pid: number) => boolean } + +/** The host name recorded in owner.json. */ +export function lockHost(): string { return hostname(); } + +export function pidAlive(pid: number): boolean { + try { process.kill(pid, 0); return true; } + catch (e) { return (e as NodeJS.ErrnoException).code === "EPERM"; } +} + +function readOwner(dir: string): Record | null { + try { + const raw = JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); + return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record : null; + } catch { return null; } +} + +function describe(dir: string, probe: LockProbe): LockInfo { + const empty: LockInfo = { present: false, token: null, host: null, pid: null, acquiredAt: null, extraEntries: [], verdict: "absent" }; + try { + const st = lstatSync(dir); + if (st.isSymbolicLink() || !st.isDirectory()) throw new DomainError("unsafe-path", "lock path is not a regular directory", 2); + } catch (e) { + if ((e as NodeJS.ErrnoException).code === "ENOENT") return empty; + throw e; + } + let names: string[] = []; + try { names = readdirSync(dir); } catch { /* reported as metadata-unavailable below */ } + const owner = readOwner(dir); + const token = typeof owner?.token === "string" ? owner.token : null; + const pid = Number.isInteger(owner?.pid) ? owner!.pid as number : null; + const host = typeof owner?.host === "string" && owner.host !== "" ? owner.host : null; + const acquiredAt = typeof owner?.acquiredAt === "string" ? owner.acquiredAt : null; + let verdict: LockVerdict; + if (token === null || pid === null) verdict = "metadata-unavailable"; + else if (host === null) verdict = "host-unknown"; + else if (host !== (probe.hostname ?? lockHost)()) verdict = "other-host"; + else verdict = (probe.isAlive ?? pidAlive)(pid) ? "live-local-pid" : "dead-local-pid"; + return { present: true, token, host, pid, acquiredAt, extraEntries: names.filter((n) => n !== "owner.json").sort(), verdict }; +} + +/** Read-only view of the scope write lock. */ +export function inspectLock(root: string, probe: LockProbe = {}): LockInfo { + return describe(join(root, WRITE_LOCK_DIR), probe); +} + +export interface RecoverRequest { requestId: string; scopeId: string; lock: { token: string; host: string; pid: number }; ownerRef: string; ownerMessageAt: string } +export interface RecoverResult { status: "ok" | "already-clear"; recovered: LockInfo | null; reason: LockVerdict | null } + +function invalid(message: string): DomainError { return new DomainError("invalid-input", message, 2); } +function exact(v: unknown, keys: string[], name: string): Record { + if (!v || typeof v !== "object" || Array.isArray(v)) throw invalid(`${name} must be an object`); + const o = v as Record; + if (Object.keys(o).some((k) => !keys.includes(k)) || keys.some((k) => !Object.hasOwn(o, k))) throw invalid(`${name} requires exactly ${keys.join(", ")}`); + return o; +} +function text(v: unknown, name: string): string { + if (typeof v !== "string" || !v.trim()) throw invalid(`${name} must be a nonempty string`); + return v; +} + +export function validateRecoverRequest(input: unknown): RecoverRequest { + if (Buffer.byteLength(canonical(input)) > MAX_REQUEST_BYTES) throw new DomainError("capacity-exceeded", "request exceeds 1 MiB; send only the fields recover needs"); + const r = exact(input, ["requestId", "scopeId", "lock", "ownerRef", "ownerMessageAt"], "recover request"); + text(r.requestId, "requestId"); text(r.scopeId, "scopeId"); text(r.ownerRef, "ownerRef"); text(r.ownerMessageAt, "ownerMessageAt"); + const lock = exact(r.lock, ["token", "host", "pid"], "lock"); + text(lock.token, "lock.token"); text(lock.host, "lock.host"); + if (!Number.isInteger(lock.pid)) throw invalid("lock.pid must be an integer"); + return r as unknown as RecoverRequest; +} + +/** + * Owner-only: remove the write lock named in the request. The request must repeat the token, host and pid that + * `check` reported, so the owner approves exactly one lock. Refused when the lock changed, holds anything but + * owner.json, names no host (a pre-S2 lock), or names this host and a pid that is still running. + * The lock folder is first renamed atomically, so two recoveries or a racing writer never both act on it. + */ +export function recoverLock(entry: { id: string; root: string }, input: unknown, probe: LockProbe = {}): RecoverResult { + const request = validateRecoverRequest(input); + if (request.scopeId !== entry.id) throw new DomainError("scope-mismatch", "request scope differs from selected scope"); + const lockDir = join(entry.root, WRITE_LOCK_DIR); + const info = describe(lockDir, probe); + if (!info.present) return { status: "already-clear", recovered: null, reason: null }; + if (info.token !== request.lock.token || info.host !== request.lock.host || info.pid !== request.lock.pid) { + throw new DomainError("lock-changed", "the lock differs from the one named in the request; run check again and show the owner the current lock", 3); + } + if (info.extraEntries.length) throw new DomainError("lock-unexpected-contents", `lock folder holds ${info.extraEntries.join(", ")} besides owner.json; inspect it by hand`, 3); + if (info.verdict === "live-local-pid") throw new DomainError("lock-owner-alive", `pid ${info.pid} on this host is still running; wait for it to finish`, 4); + if (info.verdict === "host-unknown") throw new DomainError("lock-host-unknown", "the lock records no host (written by an older mozak); remove it by hand after making sure no writer runs anywhere", 3); + if (info.verdict === "metadata-unavailable") throw new DomainError("recovery-required", "lock metadata unavailable; remove it by hand after making sure no writer runs anywhere", 4); + const moved = join(entry.root, `${WRITE_LOCK_DIR}.recover-${randomUUID()}`); + try { renameSync(lockDir, moved); } + catch (e) { + if ((e as NodeJS.ErrnoException).code === "ENOENT") return { status: "already-clear", recovered: null, reason: null }; + throw e; + } + const after = describe(moved, probe); + if (after.token !== info.token || after.extraEntries.length) { + // Someone replaced the lock between inspection and rename. Put it back untouched. + try { renameSync(moved, lockDir); } + catch { throw new DomainError("recovery-required", `lock changed during recovery and could not be restored; it is at ${moved}`, 4); } + throw new DomainError("lock-changed", "the lock changed during recovery; it was restored untouched", 3); + } + unlinkSync(join(moved, "owner.json")); + rmdirSync(moved); + fsyncDir(entry.root); + return { status: "ok", recovered: info, reason: info.verdict }; +} diff --git a/packages/core/src/notes.ts b/packages/core/src/notes.ts new file mode 100644 index 0000000..377a9a6 --- /dev/null +++ b/packages/core/src/notes.ts @@ -0,0 +1,177 @@ +// Note-level helpers shared by locator resolution and cited-note staleness. +// Everything here is read only and derives time from git: nothing is stored. + +import { execFileSync } from "node:child_process"; +import { existsSync, readdirSync, realpathSync, statSync } from "node:fs"; +import { basename, dirname, join, relative, sep } from "node:path"; +import { foldKey } from "./fold.ts"; + +/** When something was last changed, derived from git. Nothing is stored, so there is no timestamp to forget to update. */ +export interface Touched { + /** Unix seconds, or null when nothing is known. */ + epoch: number | null; + /** commit: last commit. uncommitted: working tree is newer than the last commit. none: no git history. */ + source: "commit" | "uncommitted" | "none"; +} + +export const NO_TOUCH: Touched = { epoch: null, source: "none" }; +/** Folders never walked for notes. Dot folders are skipped too. */ +export const NOTE_SKIP = new Set([".git", "node_modules", ".obsidian", "dist", "target"]); + +function git(root: string, args: string[]): string | null { + try { + return execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); + } catch { + return null; // not a repo, or git is missing + } +} + +export function gitRoot(dir: string): string | null { + const out = git(dir, ["rev-parse", "--show-toplevel"]); + return out ? realpathSync(out.trim()) : null; +} + +/** Paths with uncommitted changes (modified or untracked), relative to the repo root. */ +export function dirtyPaths(root: string): string[] { + const out = git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]); + if (!out) return []; + const parts = out.split("\0").filter(Boolean); + const paths: string[] = []; + for (let i = 0; i < parts.length; i++) { + const entry = parts[i]; + paths.push(entry.slice(3)); + if (entry[0] === "R" || entry[0] === "C") i++; // renames carry the old path as the next field + } + return paths; +} + +/** + * Last change to a file or directory. A directory counts any file inside it. + * `dirty` lets a caller pass the repo's dirty paths once instead of running git status per file. + */ +export function touched(target: string, dirty?: { root: string; paths: string[] }): Touched { + if (!existsSync(target)) return NO_TOUCH; + const real = realpathSync(target); + const root = dirty?.root ?? gitRoot(statSync(real).isDirectory() ? real : join(real, "..")); + if (!root) return NO_TOUCH; + const rel = relative(root, real) || "."; + const logged = git(root, ["log", "-1", "--format=%ct", "--", rel]); + const committed = logged && logged.trim() ? Number(logged.trim()) : null; + let newest: number | null = null; + for (const p of dirty?.paths ?? dirtyPaths(root)) { + if (rel !== "." && p !== rel && !p.startsWith(rel + sep) && !p.startsWith(rel + "/")) continue; + try { + const m = Math.floor(statSync(join(root, p)).mtimeMs / 1000); + if (newest === null || m > newest) newest = m; + } catch { + /* deleted file, no mtime to read */ + } + } + if (newest !== null && (committed === null || newest > committed)) return { epoch: newest, source: "uncommitted" }; + return committed !== null ? { epoch: committed, source: "commit" } : NO_TOUCH; +} + +/** Every .md file under dir, skipping dot folders and NOTE_SKIP. */ +export function mdFiles(dir: string, out: string[] = []): string[] { + let entries; + try { + entries = readdirSync(dir, { withFileTypes: true }); + } catch { + return out; + } + for (const e of entries) { + if (NOTE_SKIP.has(e.name) || e.name.startsWith(".")) continue; + const p = join(dir, e.name); + if (e.isDirectory()) mdFiles(p, out); + else if (e.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** Note name key: the basename without .md, lowercased and folded, as Obsidian matches names case-insensitively. */ +export const noteKey = (name: string) => foldKey(name.replace(/\.md$/i, "")).trim(); + +/** Lowercase folded note name -> every path with that name, in sorted path order. */ +export type NoteIndex = Map; + +export function noteIndex(dirs: string[]): NoteIndex { + const idx: NoteIndex = new Map(); + const seen = new Set(); + for (const dir of dirs) { + for (const f of mdFiles(dir).sort()) { + if (seen.has(f)) continue; + seen.add(f); + const key = noteKey(basename(f)); + const list = idx.get(key); + if (list) list.push(f); + else idx.set(key, [f]); + } + } + return idx; +} + +/** Text with fenced code blocks and inline code spans blanked out, so links inside code do not count. */ +export function stripCode(text: string): string { + const lines = text.split("\n"); + const out: string[] = []; + let fence: string | null = null; + for (const line of lines) { + const m = /^\s{0,3}(`{3,}|~{3,})/.exec(line); + if (fence) { + if (m && m[1][0] === fence[0] && m[1].length >= fence.length && line.trim() === m[1]) fence = null; + out.push(""); + continue; + } + if (m) { + fence = m[1]; + out.push(""); + continue; + } + out.push(line.replace(/(`+)[^`\n]*?\1/g, "")); + } + return out.join("\n"); +} + +export interface WikiLink { + /** Note name or path, without heading, block or alias. */ + target: string; + /** Heading or block after #, or null. */ + anchor: string | null; +} + +/** Wikilinks outside code: [[name]], [[name#heading]], [[name|alias]], ![[embed]]. Deduplicated, in text order. */ +export function wikiLinks(text: string): WikiLink[] { + const out: WikiLink[] = []; + const seen = new Set(); + for (const m of stripCode(text).matchAll(/!?\[\[([^\]\n]+?)\]\]/g)) { + const inner = m[1].split("|")[0]; + const hash = inner.indexOf("#"); + const target = (hash >= 0 ? inner.slice(0, hash) : inner).trim(); + const anchor = hash >= 0 ? inner.slice(hash + 1).trim() || null : null; + if (!target) continue; + const key = `${target}\0${anchor ?? ""}`; + if (seen.has(key)) continue; + seen.add(key); + out.push({ target, anchor }); + } + return out; +} + +/** Commit times (unix seconds, ascending) of every commit that changed `file`. Empty without git history. */ +export function commitTimes(root: string, file: string): number[] { + const rel = relative(root, existsSync(file) ? realpathSync(file) : file); + const out = git(root, ["log", "--format=%ct", "--", rel]); + return out ? out.split("\n").map((l) => Number(l.trim())).filter((n) => Number.isFinite(n) && n > 0).sort((a, b) => a - b) : []; +} + +/** Nearest folder at or above dir that holds a .git entry, without running git. Canonical path, or null. */ +export function findRepoRoot(dir: string): string | null { + let cur: string; + try { cur = realpathSync(dir); } catch { return null; } + for (;;) { + if (existsSync(join(cur, ".git"))) return cur; + const up = dirname(cur); + if (up === cur) return null; + cur = up; + } +} diff --git a/packages/core/src/parse.ts b/packages/core/src/parse.ts deleted file mode 100644 index af42890..0000000 --- a/packages/core/src/parse.ts +++ /dev/null @@ -1,150 +0,0 @@ -export const RELATIONS = ["depends-on", "informs", "derived-from", "translates-to"] as const; -export type Relation = (typeof RELATIONS)[number]; -export type ScopeKind = "project" | "topic"; - -export interface Link { - relation: Relation; - target: string; - line: number; -} - -export interface Assumption { - text: string; - status: "re-derived" | "open"; - line: number; -} - -export interface Translation { - title: string; - source: string; - target: string; - assumptions: Assumption[]; - line: number; -} - -export interface Issue { - code: string; - message: string; - line?: number; -} - -export interface MozakDoc { - id: string; - kind: ScopeKind; - format: number; - plan: string; - links: Link[]; - translations: Translation[]; - issues: Issue[]; -} - -const SECTIONS = ["Plan", "Links", "Translations"] as const; - -function splitFrontmatter(text: string): { fm: Record; body: string[]; offset: number } | null { - const lines = text.split(/\r?\n/); - if (lines[0]?.trim() !== "---") return null; - const end = lines.findIndex((l, i) => i > 0 && l.trim() === "---"); - if (end < 0) return null; - const fm: Record = {}; - for (const l of lines.slice(1, end)) { - const m = /^([A-Za-z_-]+):\s*(.*?)\s*(?:#.*)?$/.exec(l); - if (m) fm[m[1]] = m[2]; - } - return { fm, body: lines.slice(end + 1), offset: end + 1 }; -} - -export function isLinkTarget(target: string): boolean { - return /^https?:\/\/\S+$/.test(target) || /^\[\[[^\]\n]+\]\]$/.test(target); -} - -export function parseMozak(text: string): MozakDoc { - const issues: Issue[] = []; - const doc: MozakDoc = { id: "", kind: "project", format: 0, plan: "", links: [], translations: [], issues }; - const split = splitFrontmatter(text); - if (!split) { - issues.push({ code: "frontmatter-missing", message: "mozak.md must start with a --- frontmatter block" }); - return doc; - } - const { fm, body, offset } = split; - if (!fm.id) issues.push({ code: "id-missing", message: "frontmatter needs an id" }); - doc.id = fm.id ?? ""; - if (fm.kind === "project" || fm.kind === "topic") doc.kind = fm.kind; - else issues.push({ code: "kind-invalid", message: `kind must be project or topic, got "${fm.kind ?? ""}"` }); - doc.format = Number(fm.format); - if (doc.format !== 1) issues.push({ code: "format-unsupported", message: `format must be 1, got "${fm.format ?? ""}"` }); - - const sections = new Map(); - const order: string[] = []; - let current: string | null = null; - body.forEach((l, i) => { - const h = /^##\s+(.+?)\s*$/.exec(l); - if (h) { - current = h[1]; - if (sections.has(current)) issues.push({ code: "section-duplicate", message: `duplicate section "${current}"`, line: offset + i + 1 }); - else sections.set(current, { lines: [], start: offset + i + 1 }); - order.push(current); - } else if (current) sections.get(current)?.lines.push(l); - }); - - for (const name of SECTIONS) { - if (!sections.has(name)) issues.push({ code: "section-missing", message: `missing section "## ${name}"` }); - } - for (const name of order) { - if (!(SECTIONS as readonly string[]).includes(name)) issues.push({ code: "section-unknown", message: `unknown section "## ${name}"` }); - } - const known = order.filter((n) => (SECTIONS as readonly string[]).includes(n)); - if (known.join() !== SECTIONS.filter((n) => known.includes(n)).join()) { - issues.push({ code: "section-order", message: "sections must be in order: Plan, Links, Translations" }); - } - - doc.plan = (sections.get("Plan")?.lines ?? []).join("\n").trim(); - - const links = sections.get("Links"); - if (links) { - links.lines.forEach((raw, i) => { - const line = links.start + i + 1; - const t = raw.trim().replace(/^[-*]\s+/, ""); - if (!t) return; - const m = /^([a-z-]+):\s*(.+)$/.exec(t); - if (!m) return void issues.push({ code: "link-malformed", message: `expected "relation: target", got "${t}"`, line }); - if (!(RELATIONS as readonly string[]).includes(m[1])) { - return void issues.push({ code: "link-relation", message: `unknown relation "${m[1]}" (allowed: ${RELATIONS.join(", ")})`, line }); - } - if (!isLinkTarget(m[2])) { - return void issues.push({ code: "link-target", message: `target must be an http(s) URL or [[wikilink]], got "${m[2]}"`, line }); - } - doc.links.push({ relation: m[1] as Relation, target: m[2], line }); - }); - } - - const tr = sections.get("Translations"); - if (tr) { - let cur: Translation | null = null; - tr.lines.forEach((raw, i) => { - const line = tr.start + i + 1; - const h = /^###\s+(.+?)\s*$/.exec(raw); - if (h) { - cur = { title: h[1], source: "", target: "", assumptions: [], line }; - doc.translations.push(cur); - return; - } - const t = raw.trim().replace(/^[-*]\s+/, ""); - if (!t || !cur) return; - const f = /^(source|target):\s*(.+)$/.exec(t); - if (f) { - cur[f[1] as "source" | "target"] = f[2]; - return; - } - const a = /^\[(re-derived|open)\]\s+(.+)$/.exec(t); - if (a) cur.assumptions.push({ status: a[1] as Assumption["status"], text: a[2], line }); - }); - for (const x of doc.translations) { - if (!x.source || !x.target) issues.push({ code: "translation-incomplete", message: `translation "${x.title}" needs source: and target:`, line: x.line }); - if (x.assumptions.length === 0) issues.push({ code: "translation-no-assumptions", message: `translation "${x.title}" lists no assumptions`, line: x.line }); - for (const a of x.assumptions) { - if (a.status === "open") issues.push({ code: "translation-open-assumption", message: `translation "${x.title}" has an open assumption: ${a.text}`, line: a.line }); - } - } - } - return doc; -} diff --git a/packages/core/src/paths.ts b/packages/core/src/paths.ts new file mode 100644 index 0000000..7f29b77 --- /dev/null +++ b/packages/core/src/paths.ts @@ -0,0 +1,19 @@ +// Small path helpers shared across core and the plugin. + +import { realpathSync } from "node:fs"; +import { isAbsolute, relative } from "node:path"; + +/** Resolve symlinks. A path that does not exist (or cannot be resolved) is returned unchanged. */ +export function realOrSelf(path: string): string { + try { + return realpathSync(path); + } catch { + return path; + } +} + +/** True when `child` is `parent` or lies under it. Lexical: callers resolve symlinks first when that matters. */ +export function isWithin(child: string, parent: string): boolean { + const r = relative(parent, child); + return r === "" || (!r.startsWith("..") && !isAbsolute(r)); +} diff --git a/packages/core/src/plan.ts b/packages/core/src/plan.ts deleted file mode 100644 index 2ac29ea..0000000 --- a/packages/core/src/plan.ts +++ /dev/null @@ -1,11 +0,0 @@ -/** Replace only the body of the "## Plan" section. Links and Translations are never touched. */ -export function setPlan(text: string, newPlan: string): string { - const lines = text.split(/\r?\n/); - const start = lines.findIndex((l) => /^##\s+Plan\s*$/.test(l)); - if (start < 0) throw new Error('mozak.md has no "## Plan" section'); - let end = lines.findIndex((l, i) => i > start && /^##\s/.test(l)); - if (end < 0) end = lines.length; - if (/^##\s/m.test(newPlan)) throw new Error("plan text must not contain ## headings, they would change the file structure"); - const body = newPlan.replace(/\s+$/, ""); - return [...lines.slice(0, start + 1), "", ...(body ? [body, ""] : []), ...lines.slice(end)].join("\n"); -} diff --git a/packages/core/src/plans-index.ts b/packages/core/src/plans-index.ts new file mode 100644 index 0000000..623b554 --- /dev/null +++ b/packages/core/src/plans-index.ts @@ -0,0 +1,100 @@ +// plans.md (D3 goal 3, "built regardless"): one generated index per git repository that holds scopes, written at that +// repository's root. Titles and states only: no purposes, outcomes, evidence or decisions, so a private root never +// leaks plan text into it. A repository only lists its own scopes, so a company vault's file never names a personal +// plan and the other way round. Rejected drafts are left out. Read-only except for the plans.md files themselves. + +import { existsSync, readFileSync } from "node:fs"; +import { join, relative, sep } from "node:path"; +import { mdText, planDisplayState, type PlanDisplayState } from "./bridge.ts"; +import { replaceFileDurable } from "./durable.ts"; +import { DomainError } from "./errors.ts"; +import { findRepoRoot } from "./notes.ts"; +import { realOrSelf } from "./paths.ts"; +import type { ScopeInventory } from "./scope-index.ts"; +import { readScopeQuiet } from "./scope-store.ts"; +import type { ScopeState } from "./understanding.ts"; + +export const PLANS_INDEX_FILE = "plans.md"; +export const PLANS_INDEX_MARKER = ""; + +const SHOWN: PlanDisplayState[] = ["open", "paused", "awaiting", "completed"]; +const STATE_LABEL: Record = { open: "open", paused: "paused", awaiting: "awaiting approval", completed: "completed" }; + +export interface PlansIndexScope { + id: string; + /** Scope folder relative to the repository root, "/"-separated; "." for a scope at the root. */ + folder: string; + status: "ok" | "failed"; + code?: string; + plans: number; +} + +export interface PlansIndexFile { + repo: string; + path: string; + scopes: PlansIndexScope[]; + plans: number; + /** written: replaced or created. unchanged: same bytes. conflict: an existing plans.md without the marker. printed: not written. */ + result: "written" | "unchanged" | "conflict" | "printed"; + content: string; +} + +export interface PlansIndexSkip { scope: string; reason: "repo-mode-remote" | "not-in-git-repo" } + +export interface PlansIndexResult { files: PlansIndexFile[]; skipped: PlansIndexSkip[] } + +/** The text of one repository's plans.md. Pure. Scopes sorted by folder, plans by state then title then id. */ +export function renderPlansIndex(scopes: { id: string; folder: string; state: ScopeState | null }[]): string { + const lines = [PLANS_INDEX_MARKER, "", "# Plans", "", "Titles and states of the mozak plans in this repository. Each scope's mozak.md has the detail."]; + for (const s of [...scopes].sort((a, b) => a.folder.localeCompare(b.folder) || a.id.localeCompare(b.id))) { + lines.push("", `## ${mdText(s.state?.scope.title || s.id)}`, "", `Scope \`${s.id}\`, folder \`${s.folder}\`.`, ""); + if (!s.state) { lines.push("- (could not be read)"); continue; } + const rows = s.state.plans + .map((p) => ({ p, state: planDisplayState(p), title: (p.accepted ?? p.pending)?.content.title || p.id })) + .filter((r) => SHOWN.includes(r.state)) + .sort((a, b) => SHOWN.indexOf(a.state) - SHOWN.indexOf(b.state) || a.title.localeCompare(b.title) || a.p.id.localeCompare(b.p.id)); + if (!rows.length) lines.push("- no plans"); + for (const r of rows) lines.push(`- ${STATE_LABEL[r.state]}: ${mdText(r.title)} (${/^[A-Za-z0-9._-]+$/.test(r.p.id) ? `\`${r.p.id}\`` : mdText(r.p.id)})`); + } + return `${lines.join("\n")}\n`; +} + +/** + * Build plans.md for every repository in the inventory. `write: false` only returns the text. Never fetches: repo-mode + * remote scopes are skipped (their plans live in a code repo, not a vault), and scopes outside git are skipped. + */ +export function plansIndex(inv: ScopeInventory, opts: { write: boolean }): PlansIndexResult { + const byRepo = new Map(); + const skipped: PlansIndexSkip[] = []; + for (const entry of inv.scopes) { + if (entry.remote && entry.remote.plansMode === "repo") { skipped.push({ scope: entry.id, reason: "repo-mode-remote" }); continue; } + const repo = findRepoRoot(entry.root); + if (!repo) { skipped.push({ scope: entry.id, reason: "not-in-git-repo" }); continue; } + const folder = relative(repo, realOrSelf(entry.root)).split(sep).join("/") || "."; + let state: ScopeState | null = null; + let code: string | undefined; + try { state = readScopeQuiet(entry).state; } + catch (err) { if (!(err instanceof DomainError)) throw err; code = err.code; } + const list = byRepo.get(repo) ?? []; + list.push({ id: entry.id, folder, state, ...(code ? { code } : {}) }); + byRepo.set(repo, list); + } + const files: PlansIndexFile[] = []; + for (const [repo, scopes] of [...byRepo].sort((a, b) => a[0].localeCompare(b[0]))) { + const content = renderPlansIndex(scopes); + const path = join(repo, PLANS_INDEX_FILE); + let result: PlansIndexFile["result"] = "printed"; + if (opts.write) { + const existing = existsSync(path) ? readFileSync(path, "utf8") : null; + if (existing !== null && !existing.startsWith(PLANS_INDEX_MARKER.slice(0, 26))) result = "conflict"; + else if (existing === content) result = "unchanged"; + else { replaceFileDurable(path, content); result = "written"; } + } + const shownScopes: PlansIndexScope[] = scopes.map((s) => ({ + id: s.id, folder: s.folder, status: s.state ? "ok" : "failed", ...(s.code ? { code: s.code } : {}), + plans: s.state ? s.state.plans.filter((p) => SHOWN.includes(planDisplayState(p))).length : 0, + })); + files.push({ repo, path, scopes: shownScopes, plans: shownScopes.reduce((n, s) => n + s.plans, 0), result, content }); + } + return { files, skipped }; +} diff --git a/packages/core/src/prune.ts b/packages/core/src/prune.ts new file mode 100644 index 0000000..ebbf051 --- /dev/null +++ b/packages/core/src/prune.ts @@ -0,0 +1,53 @@ +// S2 `plan prune --rejected`: remove owner-rejected plans from mozak.json. The prune record is the operation's +// receipt, `{ action: "prune-rejected", ids }`. Receipts are never pruned and a 0.4.0 client already accepts any +// receipt action, so the record needs no new key in mozak.json. Refs to a pruned id resolve through it, and the id +// cannot be proposed again. + +import { DomainError } from "./errors.ts"; +import { validateScope, type ScopeState } from "./understanding.ts"; + +export const PRUNE_ACTION = "prune-rejected"; + +export interface PruneRecord { operationId: string; recordedAt: string } + +/** The receipt that pruned `planId`, or null. */ +export function prunedRecord(state: ScopeState, planId: string): PruneRecord | null { + for (const [operationId, r] of Object.entries(state.receipts)) { + if (r.result.action === PRUNE_ACTION && r.result.ids.includes(planId)) return { operationId, recordedAt: r.recordedAt }; + } + return null; +} + +/** A plan the owner rejected outright: it was never accepted and its only revision is rejected. */ +export function isRejectedPlan(state: ScopeState, planId: string): boolean { + const p = state.plans.find((x) => x.id === planId); + return !!p && !p.accepted && p.pending?.reviewState === "rejected"; +} + +export function rejectedPlanIds(state: ScopeState): string[] { + return state.plans.filter((p) => isRejectedPlan(state, p.id)).map((p) => p.id).sort(); +} + +/** + * Pure: a copy of `state` without the named plans. Refuses a plan that is not rejected, and a plan that another + * plan still references (a merge, a reasoning link): removing it would make mozak.json invalid. + */ +export function withoutRejectedPlans(state: ScopeState, planIds: string[]): ScopeState { + if (!planIds.length) throw new DomainError("invalid-input", "name at least one rejected plan to prune", 2); + if (new Set(planIds).size !== planIds.length) throw new DomainError("invalid-input", "planIds must be unique", 2); + for (const id of planIds) { + if (!state.plans.some((p) => p.id === id)) throw new DomainError("stale-reference", `plan "${id}" is not in this scope`, 3); + if (!isRejectedPlan(state, id)) throw new DomainError("prune-not-rejected", `plan "${id}" is not a rejected plan; only rejected plans can be pruned`, 3); + } + const drop = new Set(planIds); + const next = structuredClone(state); + next.plans = next.plans.filter((p) => !drop.has(p.id)); + try { validateScope(next); } + catch (e) { + if (!(e instanceof DomainError)) throw e; + // Name the plan that is still referenced, so the owner can leave it out. + const blocking = planIds.filter((id) => { const one = structuredClone(state); one.plans = one.plans.filter((p) => p.id !== id); try { validateScope(one); return false; } catch { return true; } }); + throw new DomainError("prune-referenced", `${blocking.length ? `plan ${blocking.join(", ")}` : "the selection"} is still referenced by another plan (${e.message}); leave it out`, 3); + } + return next; +} diff --git a/packages/core/src/rebase.ts b/packages/core/src/rebase.ts new file mode 100644 index 0000000..b1c6232 --- /dev/null +++ b/packages/core/src/rebase.ts @@ -0,0 +1,108 @@ +import { DomainError } from "./errors.ts"; +import { outcomeStatus } from "./review.ts"; +import type { Observation, Plan, Receipt, ReasoningLink, ScopeState } from "./understanding.ts"; + +/** + * Read-set rebase (S1b), used only when `concurrency.rebase` is on in mozak-settings.json. + * + * A write whose `expected` snapshot is stale may still commit when every write since that snapshot commutes + * with it. Only appends are rebased: observe, save-discussion and propose of a new plan. Everything else, + * including every owner decision, revise, complete and attach-spec, keeps the exact snapshot check. + * + * The writes since the snapshot are found through receipts: the snapshot revision must be the current revision + * or the storageRevision of a retained receipt, and the later receipts are those recorded after it. The state + * at the snapshot is reconstructed by removing what those appends added. Receipt order comes from recordedAt, + * so a write merged by git from a host whose clock lags can be missed. As a guard, any non-rebasable receipt + * recorded up to REBASE_GUARD_MS before the snapshot's receipt also refuses the rebase. + */ +export const REBASABLE_ACTIONS: ReadonlySet = new Set(["observe", "save-discussion", "propose"]); +export const REBASE_GUARD_MS = 1000; + +export interface Rebased { from: string; onto: string } +interface Snap { revision: string; graphHash: string } + +function refuse(why: string): never { + throw new DomainError("stale-input", `snapshot changed and rebase was refused: ${why}; reread before submitting a new operation`, 3); +} + +const key = (planId: string, id: string) => JSON.stringify([planId, id]); + +/** Throws stale-input unless the request's read set is unchanged between `expected` and the fresh state. */ +export function checkRebase(fresh: ScopeState, current: Snap, expected: Snap, action: string, payload: Record, guardMs = REBASE_GUARD_MS): Rebased { + if (!REBASABLE_ACTIONS.has(action)) refuse(`${action} is never rebased`); + const receipts = Object.values(fresh.receipts); + let later: Receipt[] = []; + if (expected.revision === current.revision) { + // Same revision with other graph bytes is a hand edit: what changed is unknown. + if (expected.graphHash !== current.graphHash) refuse("mozak.json changed without a new revision"); + } else { + const base = receipts.find(r => r.storageRevision === expected.revision); + if (!base) refuse("the snapshot revision is neither current nor a retained receipt"); + const at = Date.parse(base.recordedAt); + later = receipts.filter(r => r !== base && Date.parse(r.recordedAt) >= at); + const head = receipts.find(r => r.storageRevision === current.revision); + if (!head || !later.includes(head)) refuse("the writes since the snapshot cannot be ordered"); + const blocking = receipts.find(r => r !== base && Date.parse(r.recordedAt) >= at - guardMs && !REBASABLE_ACTIONS.has(r.result.action)); + if (blocking) refuse(`an intervening ${blocking.result.action} does not commute`); + } + const before = structuredClone(fresh); + const added = new Set(); // plan, observation or link added since the snapshot + const addedPlans = new Set(); + const superseded = new Set(); // plan, observation superseded since the snapshot + const discussions = new Set(); + for (const r of later) { + const [first, ...rest] = r.result.ids; + if (r.result.action === "propose") { + before.plans = before.plans.filter(p => !(p.id === first && p.createdAt === r.recordedAt)); + addedPlans.add(first!); + } else if (r.result.action === "observe") { + for (const plan of before.plans) { + const hit = plan.observations.filter(o => o.id === first && o.recordedAt === r.recordedAt); + if (!hit.length) continue; + for (const o of hit) { + added.add(key(plan.id, o.id)); + if (o.supersedesObservationId !== undefined) superseded.add(key(plan.id, o.supersedesObservationId)); + } + plan.observations = plan.observations.filter(o => !hit.includes(o)); + const links = new Set(rest); + for (const l of plan.reasoningLinks) if (links.has(l.id)) added.add(key(plan.id, l.id)); + plan.reasoningLinks = plan.reasoningLinks.filter(l => !links.has(l.id)); + } + } else { + discussions.add(first!); + if (r.result.discussion) discussions.add(r.result.discussion.id); + } + } + const planId = payload.planId as string; + const freshPlan = fresh.plans.find(p => p.id === planId); + const oldPlan = before.plans.find(p => p.id === planId); + if (action === "propose") { + if (addedPlans.has(planId) && freshPlan) refuse(`plan id "${planId}" was taken since the snapshot`); + return { from: expected.revision, onto: current.revision }; + } + if (!freshPlan || !oldPlan) refuse(`plan "${planId}" changed since the snapshot`); + if (action === "save-discussion") { + if (freshPlan.discussion && discussions.has(freshPlan.discussion.id)) refuse(`the discussion of "${planId}" was saved since the snapshot`); + return { from: expected.revision, onto: current.revision }; + } + const observation = payload.observation as Observation; + const links = (payload.reasoningLinks as ReasoningLink[] | undefined) ?? []; + if (added.has(key(planId, observation.id))) refuse(`observation id "${observation.id}" was used since the snapshot`); + for (const l of links) if (added.has(key(planId, l.id))) refuse(`reasoning link id "${l.id}" was used since the snapshot`); + if (observation.supersedesObservationId !== undefined && superseded.has(key(planId, observation.supersedesObservationId))) { + refuse(`observation "${observation.supersedesObservationId}" was superseded since the snapshot`); + } + for (const l of links) { + if (added.has(key(l.from.planId, l.from.id))) refuse(`link source "${l.from.id}" was added since the snapshot`); + if (superseded.has(key(l.from.planId, l.from.id))) refuse(`link source "${l.from.id}" was superseded since the snapshot`); + const now = fresh.plans.find(p => p.id === l.to.planId); + const then = before.plans.find(p => p.id === l.to.planId); + if (!now || !then || revisions(now) !== revisions(then)) refuse(`plan "${l.to.planId}" changed revision since the snapshot`); + if (outcomeStatus(fresh, now, l.to.id) !== outcomeStatus(before, then, l.to.id)) refuse(`outcome "${l.to.id}" changed status since the snapshot`); + } + return { from: expected.revision, onto: current.revision }; +} + +function revisions(plan: Plan): string { + return JSON.stringify([plan.accepted?.id ?? null, plan.pending?.id ?? null, plan.lifecycle.state]); +} diff --git a/packages/core/src/remote-meta.ts b/packages/core/src/remote-meta.ts index e533ac1..67d3173 100644 --- a/packages/core/src/remote-meta.ts +++ b/packages/core/src/remote-meta.ts @@ -66,6 +66,8 @@ export interface RemoteMeta { lastFetchAt: string | null; lastError: string | null; fullClone: string | null; + /** Last fetch attempt, successful or not. After a failure, reads skip the network until it is ten minutes old. */ + lastAttemptAt?: string | null; /** Last unauthenticated GitHub visibility answer for a repo-mode scope, and when it was taken. */ visibility?: Visibility | null; visibilityCheckedAt?: string | null; @@ -83,7 +85,7 @@ export function readRemoteMeta(baseDir: string, id: string): RemoteMeta { const raw = JSON.parse(readFileSync(metaPath(baseDir, id), "utf8")) as Record; const str = (v: unknown) => (typeof v === "string" && v !== "" ? v : null); const vis = raw.visibility === "public" || raw.visibility === "private-or-missing" || raw.visibility === "unknown" ? raw.visibility : null; - return { lastFetchAt: str(raw.lastFetchAt), lastError: str(raw.lastError), fullClone: str(raw.fullClone), visibility: vis, visibilityCheckedAt: str(raw.visibilityCheckedAt) }; + return { lastFetchAt: str(raw.lastFetchAt), lastError: str(raw.lastError), fullClone: str(raw.fullClone), visibility: vis, visibilityCheckedAt: str(raw.visibilityCheckedAt), lastAttemptAt: str(raw.lastAttemptAt) }; } catch { return empty; } @@ -106,4 +108,10 @@ export interface RemoteStatus { error?: string; /** "full-clone" when reads use a clone made by `mozak pull`, "vault" when plans live in a vault folder, otherwise "sparse-cache". */ source: "sparse-cache" | "full-clone" | "vault"; + /** + * "fetched": refreshed by this call. "cached": the last fetch is under ten minutes old, nothing was fetched. + * "offline": the fetch failed (now or within the last ten minutes) and the cached copy is used. + * "local": plans live in a vault folder and are never fetched. + */ + remoteFreshness: "fetched" | "cached" | "offline" | "local"; } diff --git a/packages/core/src/remote.ts b/packages/core/src/remote.ts index b083f46..bfd1aef 100644 --- a/packages/core/src/remote.ts +++ b/packages/core/src/remote.ts @@ -137,7 +137,7 @@ function refresh(entry: ScopeEntry): void { git(["merge", "--ff-only", "--quiet", "FETCH_HEAD"], dir); } -export function statusOf(entry: ScopeEntry, stale: boolean, error?: string): RemoteStatus { +export function statusOf(entry: ScopeEntry, stale: boolean, error?: string, freshness?: RemoteStatus["remoteFreshness"]): RemoteStatus { const r = remoteOf(entry); if (r.plansMode === "vault") return vaultStatus(entry); const meta = readRemoteMeta(r.baseDir, entry.id); @@ -149,18 +149,21 @@ export function statusOf(entry: ScopeEntry, stale: boolean, error?: string): Rem lastFetchAt: meta.lastFetchAt, ...(error ? { error } : {}), source: r.fullClone !== null && r.fullClone === entry.root ? "full-clone" : "sparse-cache", + remoteFreshness: freshness ?? (stale ? "offline" : "cached"), }; } /** Status row for a vault-plans scope. Plans are local, so nothing is fetched and nothing is ever stale. */ export function vaultStatus(entry: ScopeEntry): RemoteStatus { const r = remoteOf(entry); - return { scope: entry.id, remote: r.spec, ref: r.ref, stale: false, lastFetchAt: null, source: "vault" }; + return { scope: entry.id, remote: r.spec, ref: r.ref, stale: false, lastFetchAt: null, source: "vault", remoteFreshness: "local" }; } /** * Refresh one remote scope when forced or when the last successful fetch is older than ten minutes. * A fetch failure never throws: the cached copy is used and reported stale. + * After a failed fetch, unforced reads use the cached copy for ten minutes without retrying the network, so an + * offline machine does not pay a git timeout on every read. `mozak sync` and writes always force a fetch. * Vault-plans scopes never run git: their plans are local and the repo is linked for display only. */ export function syncRemote(entry: ScopeEntry, opts: { force?: boolean; now?: Date } = {}): RemoteStatus { @@ -170,15 +173,17 @@ export function syncRemote(entry: ScopeEntry, opts: { force?: boolean; now?: Dat const meta = readRemoteMeta(r.baseDir, entry.id); const have = isRepo(entry.root); const age = meta.lastFetchAt ? now.getTime() - Date.parse(meta.lastFetchAt) : Infinity; - if (!opts.force && have && meta.lastError === null && age < FRESH_MS) return statusOf(entry, false); + if (!opts.force && have && meta.lastError === null && age < FRESH_MS) return statusOf(entry, false, undefined, "cached"); + const attemptAge = meta.lastAttemptAt ? now.getTime() - Date.parse(meta.lastAttemptAt) : Infinity; + if (!opts.force && have && meta.lastError !== null && attemptAge >= 0 && attemptAge < FRESH_MS) return statusOf(entry, true, meta.lastError, "offline"); try { refresh(entry); - writeRemoteMeta(r.baseDir, entry.id, { ...meta, lastFetchAt: now.toISOString(), lastError: null, fullClone: meta.fullClone }); - return statusOf(entry, false); + writeRemoteMeta(r.baseDir, entry.id, { ...meta, lastFetchAt: now.toISOString(), lastError: null, fullClone: meta.fullClone, lastAttemptAt: now.toISOString() }); + return statusOf(entry, false, undefined, "fetched"); } catch (err) { if (!(err instanceof GitFailure)) throw err; - writeRemoteMeta(r.baseDir, entry.id, { ...meta, lastError: err.message }); - return statusOf(entry, true, err.message); + writeRemoteMeta(r.baseDir, entry.id, { ...meta, lastError: err.message, lastAttemptAt: now.toISOString() }); + return statusOf(entry, true, err.message, "offline"); } } diff --git a/packages/core/src/review.ts b/packages/core/src/review.ts index 981189e..96ee861 100644 --- a/packages/core/src/review.ts +++ b/packages/core/src/review.ts @@ -7,6 +7,7 @@ import { checkQuestionInputs, discussionCurrent, saveDiscussion } from "./conver import { DomainError } from "./errors.ts"; import { nonEmptyString } from "./validate.ts"; import { isDeletedPlanId } from "./delete.ts"; +import { prunedRecord } from "./prune.ts"; import { canonical, discussionDigest, @@ -468,7 +469,7 @@ const SIMILARITY_STOPWORDS = new Set([ "third", "key", "queued", "remote", "full", "vault", "alpha", "beta", "make", "add", "use", "users", ]); -function significantTokens(text: string): string[] { +export function significantTokens(text: string): string[] { const raw = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []; const out = new Set(); for (const word of raw) { @@ -496,6 +497,58 @@ export interface SimilarPlanMatch { lifecycleState: Plan["lifecycle"]["state"]; } +/** Token sets one plan contributes to the similarity rules. Built once per plan so a pooled report stays O(n) in tokenizing. */ +export interface SimilarityProfile { + title: string[]; + id: string[]; + body: string[]; + idNums: string[]; +} + +/** `fold` maps text before tokenizing (the pooled report folds Croatian diacritics). The propose guard uses none. */ +export function similarityProfile(planId: string, content: PlanContent, fold: (s: string) => string = (s) => s): SimilarityProfile { + return { + title: significantTokens(fold(content.title)), + id: significantTokens(fold(planId)), + body: significantTokens(fold(`${content.title} ${content.purpose} ${content.outcomes.map((o) => o.statement).join(" ")}`)), + idNums: numericTokens(planId), + }; +} + +export interface SimilarityMatch { + rule: "title" | "id-and-title" | "id-and-body"; + titleShared: string[]; + titleScore: number; + bodyShared: string[]; + bodyScore: number; +} + +/** The propose guard's three threshold rules for one pair of profiles. null when none fires. */ +export function similarityMatch(cand: SimilarityProfile, exist: SimilarityProfile): SimilarityMatch | null { + const disjointIdNumbers = + cand.idNums.length > 0 && exist.idNums.length > 0 && !cand.idNums.some((n) => exist.idNums.includes(n)); + const titleMatch = overlapCoefficient(cand.title, exist.title); + const idMatch = overlapCoefficient(cand.id, exist.id); + const bodyMatch = overlapCoefficient(cand.body, exist.body); + + const strongTitleOverlap = titleMatch.shared.length >= 2 && titleMatch.score >= 0.5; + const idAndTitleOverlap = + !disjointIdNumbers && + titleMatch.shared.length >= 1 && + idMatch.shared.length >= 1 && + bodyMatch.shared.length >= 2 && + bodyMatch.score >= 0.5; + const idAndBodyOverlap = + !disjointIdNumbers && + idMatch.shared.length >= 2 && + idMatch.score >= 0.5 && + bodyMatch.shared.length >= 2 && + bodyMatch.score >= 0.4; + const rule = strongTitleOverlap ? "title" : idAndTitleOverlap ? "id-and-title" : idAndBodyOverlap ? "id-and-body" : null; + if (!rule) return null; + return { rule, titleShared: titleMatch.shared, titleScore: titleMatch.score, bodyShared: bodyMatch.shared, bodyScore: bodyMatch.score }; +} + /** * Finds existing non-completed plans in the scope whose title, ID, purpose, or outcomes * substantially overlap a candidate proposal. Completed plans remain historical and are excluded. @@ -506,46 +559,14 @@ export function findSimilarPlans( distinctFromPlanIds: string[] = [], ): SimilarPlanMatch[] { const distinct = new Set(distinctFromPlanIds); - const candTitle = significantTokens(candidate.content.title); - const candId = significantTokens(candidate.planId); - const candBody = significantTokens( - `${candidate.content.title} ${candidate.content.purpose} ${candidate.content.outcomes.map((o) => o.statement).join(" ")}`, - ); - const candIdNums = numericTokens(candidate.planId); + const cand = similarityProfile(candidate.planId, candidate.content); const matches: SimilarPlanMatch[] = []; for (const plan of state.plans) { if (plan.id === candidate.planId || plan.lifecycle.state === "completed" || distinct.has(plan.id)) continue; const existing = (plan.accepted ?? plan.pending)?.content; if (!existing) continue; - const existTitle = significantTokens(existing.title); - const existId = significantTokens(plan.id); - const existBody = significantTokens( - `${existing.title} ${existing.purpose} ${existing.outcomes.map((o) => o.statement).join(" ")}`, - ); - const existIdNums = numericTokens(plan.id); - const disjointIdNumbers = - candIdNums.length > 0 && existIdNums.length > 0 && !candIdNums.some((n) => existIdNums.includes(n)); - - const titleMatch = overlapCoefficient(candTitle, existTitle); - const idMatch = overlapCoefficient(candId, existId); - const bodyMatch = overlapCoefficient(candBody, existBody); - - const strongTitleOverlap = titleMatch.shared.length >= 2 && titleMatch.score >= 0.5; - const idAndTitleOverlap = - !disjointIdNumbers && - titleMatch.shared.length >= 1 && - idMatch.shared.length >= 1 && - bodyMatch.shared.length >= 2 && - bodyMatch.score >= 0.5; - const idAndBodyOverlap = - !disjointIdNumbers && - idMatch.shared.length >= 2 && - idMatch.score >= 0.5 && - bodyMatch.shared.length >= 2 && - bodyMatch.score >= 0.4; - - if (strongTitleOverlap || idAndTitleOverlap || idAndBodyOverlap) { + if (similarityMatch(cand, similarityProfile(plan.id, existing))) { matches.push({ planId: plan.id, title: existing.title, lifecycleState: plan.lifecycle.state }); } } @@ -892,6 +913,8 @@ export function applyMutation( const planId = p.planId as string; if (next.plans.some((x) => x.id === planId)) throw invalid(`plan "${planId}" already exists`); if (isDeletedPlanId(next, planId)) throw invalid(`plan "${planId}" was deleted from this scope; choose a new plan id`); + // A pruned id stays reserved: refs to it resolve through its prune record. + if (prunedRecord(next, planId)) throw invalid(`plan id "${planId}" belonged to a pruned rejected plan; choose another id`); const content = checkContent(p.content); const distinctFromPlanIds = (p.distinctFromPlanIds as string[] | undefined) ?? []; for (const distinctId of distinctFromPlanIds) { diff --git a/packages/core/src/scope-index.ts b/packages/core/src/scope-index.ts index 4a5e1f6..4a3144a 100644 --- a/packages/core/src/scope-index.ts +++ b/packages/core/src/scope-index.ts @@ -27,11 +27,15 @@ export interface ScopeInventory { scopes: ScopeEntry[]; /** SHA-256 over the normalized explicit inventory: format plus sorted id and canonical root. */ digest: string; + /** Absolute inventory file path, set by loadInventory as a non-enumerable property. */ + readonly path?: string; } const INVENTORY_KEYS = ["format", "scopes"] as const; const ENTRY_KEYS = ["id", "root"] as const; const REMOTE_ENTRY_KEYS = ["id", "remote", "ref", "plans"] as const; +/** Optional on every scope entry. `focus`: the owner's starred plan ids, read by the plugin and `mozak focus` only. */ +const OPTIONAL_ENTRY_KEYS = ["focus"] as const; const REMOTE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/; function isPlainObject(value: unknown): value is Record { @@ -60,9 +64,10 @@ function assertClosedObject( allowed: readonly string[], where: string, file: string, + optional: readonly string[] = [], ): void { for (const key of Object.keys(value)) { - if (key !== "x" && !allowed.includes(key)) throw invalidInventory(file, `unknown key "${key}" in ${where}`); + if (key !== "x" && !allowed.includes(key) && !optional.includes(key)) throw invalidInventory(file, `unknown key "${key}" in ${where}`); } assertExtensionObject(value, where, file); for (const key of allowed) { @@ -74,6 +79,15 @@ function assertExtensionObject(value: Record, where: string, fi if ("x" in value && !isPlainObject(value.x)) throw invalidInventory(file, `"x" in ${where} must be an object`); } +/** `focus`, when present: an array of unique nonempty plan id strings. Unknown ids are a `check` warning, not an error. */ +function assertFocus(entry: Record, file: string): void { + if (!("focus" in entry)) return; + const focus = entry.focus; + if (!Array.isArray(focus) || focus.some((id) => typeof id !== "string" || id.trim() === "") || new Set(focus).size !== focus.length) { + throw invalidInventory(file, `scope "${String(entry.id)}" focus must be an array of unique plan ids`); + } +} + /** * Canonical identity for a path. Existing paths resolve through realpath. A path that does not * exist yet keeps its canonical ancestor plus the remaining lexical segments, so a root that @@ -144,15 +158,16 @@ export function loadInventory(configPath: string): ScopeInventory { if (isRemote) { // Exactly one of root or remote. The ref is optional and defaults to main. The object stays closed. for (const key of Object.keys(entry)) { - if (key !== "x" && !(REMOTE_ENTRY_KEYS as readonly string[]).includes(key)) { + if (key !== "x" && !(REMOTE_ENTRY_KEYS as readonly string[]).includes(key) && !(OPTIONAL_ENTRY_KEYS as readonly string[]).includes(key)) { throw invalidInventory(file, key === "root" ? `scope entry must have exactly one of "root" or "remote"` : `unknown key "${key}" in scope entry`); } } assertExtensionObject(entry, "scope entry", file); if (!("id" in entry)) throw invalidInventory(file, `missing "id" in scope entry`); } else { - assertClosedObject(entry, ENTRY_KEYS, "scope entry", file); + assertClosedObject(entry, ENTRY_KEYS, "scope entry", file, OPTIONAL_ENTRY_KEYS); } + assertFocus(entry, file); const id = entry.id; if (typeof id !== "string" || id.trim() === "") { @@ -218,7 +233,10 @@ export function loadInventory(configPath: string): ScopeInventory { } scopes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)); - return { format, scopes, digest: digestOf(format, scopes) }; + const inventory: ScopeInventory = { format, scopes, digest: digestOf(format, scopes) }; + // Not enumerable: the loaded inventory compares and serializes exactly as before. Used to find mozak-settings.json. + Object.defineProperty(inventory, "path", { value: file, enumerable: false }); + return inventory; } /** @@ -228,7 +246,7 @@ export function loadInventory(configPath: string): ScopeInventory { export function resolveScope(inv: ScopeInventory, id: string): ScopeEntry { const matches = inv.scopes.filter((scope) => scope.id === id); if (matches.length === 0) { - throw new DomainError("scope-not-found", `no scope "${id}" in the inventory`); + throw new DomainError("scope-not-found", `no scope "${id}" in the inventory; run mozak scopes (MCP mozak_scopes) to list the scope ids`); } const entry = matches[0]; if (matches.length > 1 || entry === undefined) { diff --git a/packages/core/src/scope-store.ts b/packages/core/src/scope-store.ts index f5f4a57..4dcccad 100644 --- a/packages/core/src/scope-store.ts +++ b/packages/core/src/scope-store.ts @@ -1,5 +1,5 @@ import { createHash, randomUUID } from "node:crypto"; -import { accessSync, constants, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync } from "node:fs"; +import { accessSync, constants, lstatSync, readFileSync, readdirSync, renameSync, unlinkSync } from "node:fs"; import { join } from "node:path"; import { DomainError } from "./errors.ts"; import { nonEmptyString as text } from "./validate.ts"; @@ -10,8 +10,12 @@ import { isGraphPath, scopeFile, scopeFileName, GRAPH_FILE, BRIDGE_FILE, LEGACY_ import { inspectSpecification } from "./spec-file.ts"; import { DELETE_ACTION, withoutPlans } from "./delete.ts"; import { renderBridge, renderBridgeLegacy, isPendingOrderRender } from "./bridge.ts"; -import { removeLeftoverTempFiles, replaceFileDurable, writeFileDurable, fsyncDir } from "./durable.ts"; +import { removeLeftoverTempFiles, replaceFileDurable, fsyncDir } from "./durable.ts"; import { ensureStorageIgnored, storageIgnoreIssues } from "./storage-hygiene.ts"; +import { ANNOTATIONS_FILE, annotationsBytes, applyAnnotate, emptyAnnotations, readAnnotations, validateAnnotateRequest, type ScopeLookup } from "./annotations.ts"; +import { checkRebase, type Rebased } from "./rebase.ts"; +import { acquireDirLock } from "./dir-lock.ts"; +import { PRUNE_ACTION, withoutRejectedPlans } from "./prune.ts"; export { renderBridge, renderBridgeLegacy } from "./bridge.ts"; @@ -23,11 +27,13 @@ export interface OperationResult { status: string; committed: boolean; operationId?: string; requestId?: string; snapshot: ScopeSnapshot | null; projectionStatus: ProjectionStatus | null; projectionUpdated: boolean; issues: ScopeIssue[]; result?: Receipt["result"]; replayed?: boolean; + /** Present only when concurrency.rebase is on and a stale snapshot was rebased onto fresh state. */ + rebased?: Rebased; } /** Internal testing seam, never accepted from CLI/MCP input. */ -export interface StoreOptions { lockTimeoutMs?: number; onPhase?: (phase: string) => void } +/** `rebase`: experimental read-set rebase (S1b), resolved by the caller from mozak-settings.json. Default off. */ +export interface StoreOptions { lockTimeoutMs?: number; onPhase?: (phase: string) => void; rebaseGuardMs?: number; rebase?: boolean } const absent = (): FileToken => ({ exists: false, sha256: null }); -const sleep = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); const own = (o: object, k: string) => Object.prototype.hasOwnProperty.call(o, k); function object(v: unknown, keys: string[], name: string, optional: string[] = []): Record { if (!v || typeof v !== "object" || Array.isArray(v)) throw new DomainError("invalid-input", `${name} must be an object`); @@ -50,7 +56,7 @@ function expected(v: unknown): ScopeSnapshot { return o as unknown as ScopeSnapshot; } function bounded(v: unknown): void { - if (Buffer.byteLength(canonical(v)) > MAX_REQUEST_BYTES) throw new DomainError("capacity-exceeded", "request exceeds 1 MiB"); + if (Buffer.byteLength(canonical(v)) > MAX_REQUEST_BYTES) throw new DomainError("capacity-exceeded", "request exceeds 1 MiB; split it into smaller operations"); } function file(path: string, max = MAX_SCOPE_BYTES): { token: FileToken; bytes: string | null; validUtf8: boolean } { try { @@ -73,9 +79,9 @@ function pathExists(path: string): boolean { const same = (a: FileToken, b: FileToken) => a.exists === b.exists && a.sha256 === b.sha256; function decode(bytes: string, entry: ScopeEntry): ScopeState { let raw: unknown; - try { raw = JSON.parse(bytes); } catch { throw new DomainError("invalid-json", "mozak.json is not valid JSON"); } + try { raw = JSON.parse(bytes); } catch { throw new DomainError("invalid-json", "mozak.json is not valid JSON; restore it from git or fix the syntax by hand, then run mozak check"); } const state = validateScope(raw); - if (state.scope.id !== entry.id) throw new DomainError("scope-mismatch", "inventory identity does not match mozak.json"); + if (state.scope.id !== entry.id) throw new DomainError("scope-mismatch", `inventory id "${entry.id}" does not match scope.id "${state.scope.id}" in mozak.json; fix the inventory entry or its root`); return state; } /** @@ -85,17 +91,31 @@ function decode(bytes: string, entry: ScopeEntry): ScopeState { * A digest stored in the bridge itself is not proof of provenance. Other content is preserved as a conflict. */ function projectStatus(state: ScopeState, graphHash: string, bridge: ReturnType, graphName: string): ProjectionStatus { - if (bridge.token.exists && bridge.token.sha256 === hashBytes(renderBridge(state, graphHash, graphName))) return "current"; + const render = renderBridge(state, graphHash, graphName); + if (bridge.token.exists && bridge.token.sha256 === hashBytes(render)) return "current"; + // CRLF line endings or trailing whitespace (git autocrlf, editors) carry no content: the note is still today's render. + if (bridge.bytes !== null && bridge.validUtf8 && whitespaceOnly(bridge.bytes, render)) return "current"; if (same(bridge.token, state.storage.previousBridge)) return "bridge-stale"; if (bridge.bytes !== null && bridge.validUtf8 && isOlderRender(state, graphHash, bridge.bytes)) return "bridge-stale"; return "bridge-conflict"; } +/** Bytes with CRLF turned into LF, trailing spaces and tabs cut from every line, and trailing blank lines dropped. */ +export function normalizeProjection(bytes: string): string { + return bytes.replace(/\r\n/g, "\n").split("\n").map((line) => line.replace(/[ \t]+$/, "")).join("\n").replace(/\n+$/, ""); +} +/** True when two renders differ only by line endings or trailing whitespace. Exact equality is not whitespace-only. */ +export function whitespaceOnly(bytes: string, render: string): boolean { + return bytes !== render && normalizeProjection(bytes) === normalizeProjection(render); +} /** Only byte-exact UTF-8 can be recognised as a generated render. Lossy decoding must never look current or stale. */ function isOlderRender(state: ScopeState, graphHash: string, bytes: string): boolean { const h = hashBytes(bytes); - return h === hashBytes(renderBridgeLegacy(state, graphHash)) + if (h === hashBytes(renderBridgeLegacy(state, graphHash)) || isPendingOrderRender(state, graphHash, bytes) - || isPendingOrderRender(state, graphHash, bytes, LEGACY_GRAPH_FILE); + || isPendingOrderRender(state, graphHash, bytes, LEGACY_GRAPH_FILE)) return true; + // An older render that only gained CRLF line endings or trailing whitespace is still that render. + const n = normalizeProjection(bytes); + return n === normalizeProjection(renderBridgeLegacy(state, graphHash)) || n === normalizeProjection(renderBridge(state, graphHash, LEGACY_GRAPH_FILE)); } /** True when the bridge is an unedited older render of this state. A write may replace it like a current one. */ function isLegacyBridge(entry: ScopeEntry, read: ScopeRead): boolean { @@ -104,10 +124,24 @@ function isLegacyBridge(entry: ScopeEntry, read: ScopeRead): boolean { return bridge.bytes !== null && bridge.validUtf8 && same(bridge.token, read.snapshot.bridge) && isOlderRender(read.state, read.snapshot.graphHash, bridge.bytes); } export function readScope(entry: ScopeEntry, options: StoreOptions = {}): ScopeRead { + return readScopeWith(entry, options, true); +} +/** Read for whole-inventory reports (plans.md, similar, locators): same state and snapshot, no git ignore diagnostics. */ +export function readScopeQuiet(entry: ScopeEntry): ScopeRead { + return readScopeWith(entry, {}, false); +} +/** + * Read inside a write: the same canonical state, snapshot and projection status, without the git ignore diagnostics. + * A write never uses those issues, and each check spawns one to three git processes (most of a commit's cost in a vault). + */ +function readForWrite(entry: ScopeEntry): ScopeRead { + return readScopeWith(entry, {}, false); +} +function readScopeWith(entry: ScopeEntry, options: StoreOptions, diagnostics: boolean): ScopeRead { assertScopeFiles(entry.root); for (let attempt = 0; attempt < 3; attempt++) { const a = file(scopeFile(entry.root, "graph")); - if (a.bytes === null) throw new DomainError("scope-uninitialized", entry.remote ? `not a scope: ${entry.remote.spec}@${entry.remote.ref} has no mozak.json at its root` : `no mozak.json for ${entry.id}`); + if (a.bytes === null) throw new DomainError("scope-uninitialized", entry.remote ? `not a scope: ${entry.remote.spec}@${entry.remote.ref} has no mozak.json at its root` : `no mozak.json for ${entry.id}; check its root in the inventory, or ask the owner to run mozak scope init`); let bridge: ReturnType | null = null; let bridgeIssue: ScopeIssue | null = null; try { bridge = file(scopeFile(entry.root, "bridge"), MAX_SCOPE_BYTES * 2); } @@ -121,7 +155,7 @@ export function readScope(entry: ScopeEntry, options: StoreOptions = {}): ScopeR if (!a.validUtf8) throw new DomainError("invalid-encoding", "mozak.json must contain valid UTF-8 bytes"); const state = decode(a.bytes, entry); const projectionStatus = bridge ? projectStatus(state, a.token.sha256!, bridge, scopeFileName(entry.root, "graph")) : "bridge-conflict"; - const issues: ScopeIssue[] = [...storageIgnoreIssues(entry.root), ...(bridgeIssue ? [bridgeIssue] : [])]; + const issues: ScopeIssue[] = [...(diagnostics ? storageIgnoreIssues(entry.root) : []), ...(bridgeIssue ? [bridgeIssue] : [])]; if (entry.inventoryExtensionsIgnored) issues.push({ code: "inventory-x-ignored", message: "Reserved inventory x object settings are ignored by this client; they do not enable any behavior." }); if (projectionStatus !== "current") issues.push({ code: projectionStatus, message: "Canonical context is available. Explicit projection repair or conflict review is required before further writes." }); for (const name of ["README.md", "AGENTS.md"]) { @@ -135,7 +169,7 @@ export function readScope(entry: ScopeEntry, options: StoreOptions = {}): ScopeR } return { state, snapshot: { revision: state.storage.revision, graphHash: a.token.sha256!, bridge: bridge?.token ?? null }, projectionStatus, issues }; } - throw new DomainError("busy", "canonical state changed during three read attempts", 4); + throw new DomainError("busy", "canonical state changed during three read attempts; another writer is active, retry in a few seconds", 4); } /** Trusted IO results never come from mutation payloads or canonical metadata. */ @@ -182,49 +216,40 @@ export function readScopeView(entry: ScopeEntry, candidatePlanId?: string, optio if (!lockFree) issues.push({ code: "storage-busy", message: "Scope lock is present or unavailable; execution eligibility is withheld, not reclaimed by age" }); return { ...after, issues: [...after.issues, ...issues], environment: { storageUsable: after.projectionStatus === "current" && lockFree, specifications } }; } - throw new DomainError("busy", "canonical/projection state changed during three specification read attempts", 4); + throw new DomainError("busy", "canonical/projection state changed during three specification read attempts; another writer is active, retry in a few seconds", 4); } function acquire(root: string, options: StoreOptions): () => void { - const lock = join(root, ".mozak-write-lock"); - const ownerPath = join(lock, "owner.json"); - const ownerToken = randomUUID(); - const deadline = Date.now() + (options.lockTimeoutMs ?? 1000); - for (;;) { - try { mkdirSync(lock, { mode: 0o700 }); break; } - catch (e) { if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e; } - try { - const st = lstatSync(lock); - if (st.isSymbolicLink() || !st.isDirectory()) throw new DomainError("unsafe-path", "lock path is not a regular directory"); - } catch (e) { - if ((e as NodeJS.ErrnoException).code === "ENOENT") continue; - throw e; - } - if (Date.now() >= deadline) { - let known = false; - try { const owner = JSON.parse(readFileSync(ownerPath, "utf8")) as { token?: unknown; pid?: unknown }; known = typeof owner.token === "string" && Number.isInteger(owner.pid); } catch { /* diagnostic only */ } - throw new DomainError(known ? "busy" : "recovery-required", known ? "scope lock is held; age and timeout do not prove owner death" : "lock metadata unavailable; wait or establish offline quiescence before recovery", 4); - } - sleep(10); - } - // A failure here intentionally leaves the lock behind for offline recovery. - options.onPhase?.("after-lock-mkdir"); - writeFileDurable(ownerPath, canonical({ token: ownerToken, pid: process.pid, processStartHint: new Date(Date.now() - process.uptime() * 1000).toISOString(), acquiredAt: new Date().toISOString() })); - fsyncDir(lock); - return () => { - const owner = JSON.parse(readFileSync(ownerPath, "utf8")) as { token?: unknown }; - if (owner.token !== ownerToken || readdirSync(lock).some(n => n !== "owner.json")) throw new DomainError("lock-ownership-conflict", "lock ownership changed or unexpected contents found; not removing it", 4); - unlinkSync(ownerPath); - rmdirSync(lock); // No work belonging to the old transaction follows this removal. - }; + return acquireDirLock(join(root, ".mozak-write-lock"), "scope", options); } interface Transaction { committed: boolean; projectionUpdated: boolean; state?: ScopeState; result?: Receipt["result"]; temporary: string[]; operationId?: string; requestId?: string; } +/** + * Take the write locks of several scope roots in path order, run `work`, then release in reverse order. Every + * multi-scope locker uses the same order and single writers hold one lock, so lockers cannot deadlock. + * A busy lock releases the ones already held and throws `busy`. Roots that do not exist are skipped. + */ +export function withScopeLocks(roots: string[], work: () => T, options: StoreOptions = {}): T { + const sorted = [...new Set(roots)].filter((root) => pathExists(root)).sort(); + const held: (() => void)[] = []; + let result: T | undefined; + let failure: unknown; + try { + for (const root of sorted) { assertScopeFiles(root); held.push(acquire(root, options)); } + options.onPhase?.("all-locked"); + result = work(); + } catch (e) { failure = e; } + let releaseError: unknown; + for (const release of held.reverse()) { try { release(); } catch (e) { releaseError ??= e; } } + if (releaseError) throw new DomainError("recovery-required", `${releaseError instanceof Error ? releaseError.message : String(releaseError)}; original failure: ${failure instanceof Error ? failure.message : "none"}`, 4); + if (failure) throw failure; + return result as T; +} function outcome(entry: ScopeEntry, tx: Transaction, status: string, issues: ScopeIssue[] = []): OperationResult { let read: ScopeRead | null = null; - try { read = readScope(entry); } catch { /* committed state is still reported even when readback fails */ } + try { read = readForWrite(entry); } catch { /* committed state is still reported even when readback fails */ } return { status, committed: tx.committed, ...(tx.operationId ? { operationId: tx.operationId } : {}), ...(tx.requestId ? { requestId: tx.requestId } : {}), snapshot: read?.snapshot ?? null, projectionStatus: read?.projectionStatus ?? null, projectionUpdated: tx.projectionUpdated, issues, ...(tx.result ? { result: tx.result } : {}) }; } function transaction(entry: ScopeEntry, options: StoreOptions, tx: Transaction, work: () => OperationResult): OperationResult { @@ -262,7 +287,7 @@ function publishGraph(entry: ScopeEntry, state: ScopeState, previousGraph: FileT state.storage.previousBridge = previousBridge; validateScope(state); const bytes = canonical(state); - if (Buffer.byteLength(bytes) > MAX_SCOPE_BYTES) throw new DomainError("capacity-exceeded", "canonical state would exceed 4 MiB"); + if (Buffer.byteLength(bytes) > MAX_SCOPE_BYTES) throw new DomainError("capacity-exceeded", "canonical state would exceed 4 MiB; ask the owner to prune rejected plans or move finished plans to another scope"); const graphPath = scopeFile(entry.root, "graph"); const bridgePath = scopeFile(entry.root, "bridge"); const recheck = (graph: FileToken) => { @@ -284,13 +309,13 @@ function publishGraph(entry: ScopeEntry, state: ScopeState, previousGraph: FileT function receipt(read: ScopeRead, operationId: string, requestDigest: string, tx: Transaction, entry: ScopeEntry): OperationResult | null { if (!own(read.state.receipts, operationId)) return null; const record = read.state.receipts[operationId]; - if (record.requestDigest !== requestDigest) throw new DomainError("operation-conflict", "operation ID was already used with different input", 3); + if (record.requestDigest !== requestDigest) throw new DomainError("operation-conflict", "operation ID was already used with different input; use a new operationId for a changed request, or read the committed result with mozak operation --id", 3); tx.committed = true; tx.result = record.result; return { ...outcome(entry, tx, "replayed"), replayed: true }; } function match(read: ScopeRead, snapshot: ScopeSnapshot, bridge = true): void { - if (bridge && (!read.snapshot.bridge || !snapshot.bridge)) throw new DomainError("bridge-unavailable", "a trustworthy bridge snapshot is required before writing", 3); - if (read.snapshot.revision !== snapshot.revision || read.snapshot.graphHash !== snapshot.graphHash || (bridge && !same(read.snapshot.bridge!, snapshot.bridge!))) throw new DomainError("stale-input", "snapshot changed; reread before submitting a new operation", 3); + if (bridge && (!read.snapshot.bridge || !snapshot.bridge)) throw new DomainError("bridge-unavailable", "a trustworthy bridge snapshot is required before writing; run mozak check to see why, and ask the owner to run mozak projection repair", 3); + if (read.snapshot.revision !== snapshot.revision || read.snapshot.graphHash !== snapshot.graphHash || (bridge && !same(read.snapshot.bridge!, snapshot.bridge!))) throw new DomainError("stale-input", "snapshot changed; reread before submitting a new operation: take the new snapshot from context as expected and use a new operationId", 3); } function identity(entry: ScopeEntry, input: Record): void { if (text(input.scopeId, "scopeId") !== entry.id) throw new DomainError("scope-mismatch", "request scope differs from selected scope"); @@ -306,7 +331,7 @@ export function initScopeState(entry: ScopeEntry, input: unknown, options: Store const tx: Transaction = { operationId, committed: false, projectionUpdated: false, temporary: [] }; return transaction(entry, options, tx, () => { if (file(scopeFile(entry.root, "graph")).token.exists) { - const prior = receipt(readScope(entry), operationId, digest(input), tx, entry); + const prior = receipt(readForWrite(entry), operationId, digest(input), tx, entry); if (prior) return prior; throw new DomainError("already-exists", "existing canonical graph cannot be initialized again", 3); } @@ -327,10 +352,16 @@ export function mutateScope(entry: ScopeEntry, input: unknown, actor: "agent" | validateMutation(r.action, r.payload, actor); const tx: Transaction = { operationId, committed: false, projectionUpdated: false, temporary: [] }; return transaction(entry, options, tx, () => { - const read = readScope(entry); + const read = readForWrite(entry); const replay = receipt(read, operationId, digest(input), tx, entry); if (replay) return replay; - match(read, snapshot); + let rebased: Rebased | undefined; + try { match(read, snapshot); } + catch (e) { + // Off by default. Only a stale snapshot is a rebase candidate; checkRebase refuses with stale-input. + if (!(e instanceof DomainError && e.code === "stale-input") || options.rebase !== true) throw e; + rebased = checkRebase(read.state, read.snapshot, snapshot, r.action as string, r.payload as Record, options.rebaseGuardMs); + } if (read.projectionStatus !== "current" && !isLegacyBridge(entry, read)) throw new DomainError(read.projectionStatus, "projection requires explicit repair or conflict resolution before new writes", 3); const now = new Date().toISOString(); const environment: ReviewEnvironment = { storageUsable: true, specifications: Object.create(null) as NonNullable }; @@ -347,7 +378,8 @@ export function mutateScope(entry: ScopeEntry, input: unknown, actor: "agent" | next.state.storage = { revision: randomUUID(), updatedAt: now, previousBridge: read.snapshot.bridge! }; Object.defineProperty(next.state.receipts, operationId, { value: { requestDigest: digest(input), storageRevision: next.state.storage.revision, recordedAt: now, result: next.result }, enumerable: true, writable: true, configurable: true }); tx.result = next.result; - return publishGraph(entry, next.state, { exists: true, sha256: read.snapshot.graphHash }, read.snapshot.bridge!, tx, options); + const published = publishGraph(entry, next.state, { exists: true, sha256: read.snapshot.graphHash }, read.snapshot.bridge!, tx, options); + return rebased ? { ...published, rebased } : published; }); } export type RenderResult = "rendered" | "current" | "conflict" | "failed"; @@ -360,11 +392,11 @@ export function renderProjection(entry: ScopeEntry, options: StoreOptions = {}): let result: RenderResult = "current"; const tx: Transaction = { committed: false, projectionUpdated: false, temporary: [] }; const out = transaction(entry, options, tx, () => { - const read = readScope(entry); + const read = readForWrite(entry); if (read.projectionStatus === "current") return outcome(entry, tx, "already-current"); if (read.projectionStatus === "bridge-conflict") { result = "conflict"; return outcome(entry, tx, "bridge-conflict", [{ code: "bridge-conflict", message: "mozak.md differs from every known render; preserved for owner review (projection repair)" }]); } options.onPhase?.("before-render"); - const again = readScope(entry); + const again = readForWrite(entry); if (canonical(again.snapshot) !== canonical(read.snapshot)) throw new DomainError("stale-input", "scope changed while rendering; rerun render", 3); publish(scopeFile(entry.root, "bridge"), renderBridge(again.state, again.snapshot.graphHash, scopeFileName(entry.root, "graph")), tx); tx.projectionUpdated = true; result = "rendered"; @@ -386,7 +418,7 @@ export function retitleScope(entry: ScopeEntry, input: unknown, options: StoreOp if (title.length > 200 || /[\r\n]/.test(title)) throw new DomainError("invalid-input", "title must be one line of at most 200 characters"); const tx: Transaction = { operationId, committed: false, projectionUpdated: false, temporary: [] }; return transaction(entry, options, tx, () => { - const read = readScope(entry); + const read = readForWrite(entry); const replay = receipt(read, operationId, digest(input), tx, entry); if (replay) return replay; match(read, snapshot); @@ -417,7 +449,7 @@ export function deletePlans(entry: ScopeEntry, input: unknown, options: StoreOpt const planIds = [...(r.planIds as string[])].sort(); const tx: Transaction = { operationId, committed: false, projectionUpdated: false, temporary: [] }; return transaction(entry, options, tx, () => { - const read = readScope(entry); + const read = readForWrite(entry); const replay = receipt(read, operationId, digest(input), tx, entry); if (replay) return replay; match(read, snapshot); @@ -427,7 +459,35 @@ export function deletePlans(entry: ScopeEntry, input: unknown, options: StoreOpt const result = { action: DELETE_ACTION, ids: planIds }; state.storage = { revision: randomUUID(), updatedAt: now, previousBridge: read.snapshot.bridge! }; Object.defineProperty(state.receipts, operationId, { value: { requestDigest: digest(input), storageRevision: state.storage.revision, recordedAt: now, result }, enumerable: true, writable: true, configurable: true }); - tx.result = result; + tx.result = result as Receipt["result"]; + return publishGraph(entry, state, { exists: true, sha256: read.snapshot.graphHash }, read.snapshot.bridge!, tx, options); + }); +} +/** + * Owner-only: remove the named rejected plans from mozak.json (`plan prune --rejected`). The request lists every + * plan id the owner saw, so approval is item by item. Same snapshot check, lock, receipt and projection as every + * other write, and never rebased. The receipt `{ action: "prune-rejected", ids }` is the prune record. + */ +export function pruneRejectedPlans(entry: ScopeEntry, input: unknown, options: StoreOptions = {}): OperationResult { + bounded(input); + const r = object(input, ["operationId", "scopeId", "expected", "planIds", "ownerRef", "ownerMessageAt"], "prune request"); + identity(entry, r); const operationId = text(r.operationId, "operationId"); const snapshot = expected(r.expected); + text(r.ownerRef, "ownerRef"); text(r.ownerMessageAt, "ownerMessageAt"); + if (!Array.isArray(r.planIds) || r.planIds.some((id) => typeof id !== "string" || !id.trim()) || r.planIds.length > 100) throw new DomainError("invalid-input", "planIds must list 1 to 100 plan ids"); + const planIds = [...(r.planIds as string[])].sort(); + const tx: Transaction = { operationId, committed: false, projectionUpdated: false, temporary: [] }; + return transaction(entry, options, tx, () => { + const read = readForWrite(entry); + const replay = receipt(read, operationId, digest(input), tx, entry); + if (replay) return replay; + match(read, snapshot); + if (read.projectionStatus !== "current" && !isLegacyBridge(entry, read)) throw new DomainError(read.projectionStatus, "projection requires explicit repair or conflict resolution before new writes", 3); + const state = withoutRejectedPlans(read.state, planIds); + const now = new Date().toISOString(); + const result = { action: PRUNE_ACTION, ids: planIds }; + state.storage = { revision: randomUUID(), updatedAt: now, previousBridge: read.snapshot.bridge! }; + Object.defineProperty(state.receipts, operationId, { value: { requestDigest: digest(input), storageRevision: state.storage.revision, recordedAt: now, result }, enumerable: true, writable: true, configurable: true }); + tx.result = result as Receipt["result"]; return publishGraph(entry, state, { exists: true, sha256: read.snapshot.graphHash }, read.snapshot.bridge!, tx, options); }); } @@ -449,7 +509,7 @@ export function renameScopeFiles(entry: ScopeEntry, options: StoreOptions = {}): if ((names.includes(GRAPH_FILE) && names.includes(LEGACY_GRAPH_FILE)) || (names.includes(BRIDGE_FILE) && names.includes(LEGACY_BRIDGE_FILE))) { throw new DomainError("rename-conflict", "both uppercase and lowercase plan files exist; keep one by hand", 3); } - const read = readScope(entry); + const read = readForWrite(entry); if (read.projectionStatus === "bridge-conflict") throw new DomainError("bridge-conflict", "mozak.md has hand edits; review them before renaming", 3); const move = (from: string, to: string) => { if (from === to) return; @@ -460,7 +520,7 @@ export function renameScopeFiles(entry: ScopeEntry, options: StoreOptions = {}): move(graphName, GRAPH_FILE); if (pathExists(join(entry.root, bridgeName))) move(bridgeName, BRIDGE_FILE); fsyncDir(entry.root); - const again = readScope(entry); + const again = readForWrite(entry); publish(join(entry.root, BRIDGE_FILE), renderBridge(again.state, again.snapshot.graphHash, GRAPH_FILE), tx); tx.projectionUpdated = true; result = "renamed"; return outcome(entry, tx, "ok"); @@ -474,7 +534,7 @@ export function repairProjection(entry: ScopeEntry, input: unknown, options: Sto identity(entry, r); const requestId = text(r.requestId, "requestId"); const snapshot = expected(r.expected); const tx: Transaction = { requestId, committed: false, projectionUpdated: false, temporary: [] }; return transaction(entry, options, tx, () => { - const read = readScope(entry); match(read, snapshot, false); + const read = readForWrite(entry); match(read, snapshot, false); if (read.projectionStatus === "current") { ensureStorageIgnored(entry.root); return outcome(entry, tx, "already-current"); @@ -482,10 +542,57 @@ export function repairProjection(entry: ScopeEntry, input: unknown, options: Sto match(read, snapshot); if (read.projectionStatus === "bridge-conflict") throw new DomainError("bridge-conflict", "manual bridge conflict preserved; automatic repair refused", 3); options.onPhase?.("before-repair"); - const current = readScope(entry); match(current, snapshot); + const current = readForWrite(entry); match(current, snapshot); ensureStorageIgnored(entry.root); publish(scopeFile(entry.root, "bridge"), renderBridge(current.state, current.snapshot.graphHash, scopeFileName(entry.root, "graph")), tx); tx.projectionUpdated = true; return outcome(entry, tx, "ok"); }); } + +export interface AnnotateOutcome extends OperationResult { annotations: FileToken | null } +/** + * Owner-only: apply owner-approved annotation items to mozak.annotations.json. Runs under the scope lock, writes one + * temp file and one rename, and never touches mozak.json or mozak.md. The CAS input is only the sidecar token the + * owner reviewed: graph writes by agents neither need nor change it, and an annotation never makes an agent stale. + * A retried identical request replays its receipt before the CAS check. `lookup` resolves targets in other scopes. + */ +export function annotateScope(entry: ScopeEntry, input: unknown, lookup: ScopeLookup, options: StoreOptions = {}): AnnotateOutcome { + bounded(input); + const { request, items } = validateAnnotateRequest(input); + identity(entry, request as unknown as Record); + const tx: Transaction = { operationId: request.operationId, committed: false, projectionUpdated: false, temporary: [] }; + let token: FileToken | null = null; + const out = transaction(entry, options, tx, () => { + const read = readForWrite(entry); + const side = readAnnotations(entry.root, entry.id); + if (side.issues.length) throw new DomainError(side.issues[0]!.code, `${side.issues[0]!.message}; repair the sidecar by hand before annotating`, 3); + const requestDigest = digest(input); + const base = { operationId: request.operationId, snapshot: read.snapshot, projectionStatus: read.projectionStatus, projectionUpdated: false, issues: [] as ScopeIssue[] }; + if (side.doc && own(side.doc.receipts, request.operationId)) { + const prior = side.doc.receipts[request.operationId]!; + if (prior.requestDigest !== requestDigest) throw new DomainError("operation-conflict", "operation ID was already used with different input; use a new operationId for a changed request, or read the committed result with mozak operation --id", 3); + tx.committed = true; tx.result = prior.result; token = side.token; + return { ...base, status: "replayed", committed: true, replayed: true, result: prior.result }; + } + if (!same(side.token, request.expectedAnnotations)) throw new DomainError("stale-input", "mozak.annotations.json changed; reread it and show the items again", 3); + const now = new Date().toISOString(); + const revision = randomUUID(); + const current = side.doc ?? emptyAnnotations(entry.id, now); + const local: ScopeLookup = (id) => (id === entry.id ? read.state : lookup(id)); + const applied = applyAnnotate(current, read.state, items, request, local, now, revision); + const result = { action: "annotate" as const, ids: applied.ids }; + Object.defineProperty(applied.doc.receipts, request.operationId, { value: { requestDigest, revision, recordedAt: now, result }, enumerable: true, writable: true, configurable: true }); + const bytes = annotationsBytes(applied.doc); + const path = join(entry.root, ANNOTATIONS_FILE); + options.onPhase?.("before-annotations"); + replaceFileDurable(path, bytes, (temporary) => tx.temporary.push(temporary), () => { + options.onPhase?.("temp-written:annotations"); + if (!same(readAnnotations(entry.root).token, side.token)) throw new DomainError("annotations-changed-during-write", "mozak.annotations.json changed during the write; external bytes preserved", 3); + }); + tx.committed = true; tx.result = result; + token = { exists: true, sha256: hashBytes(bytes) }; + return { ...base, status: "ok", committed: true, result }; + }); + return { ...out, annotations: token }; +} diff --git a/packages/core/src/settings.ts b/packages/core/src/settings.ts new file mode 100644 index 0000000..d9e25d7 --- /dev/null +++ b/packages/core/src/settings.ts @@ -0,0 +1,160 @@ +// mozak-settings.json: optional per-installation settings, next to the inventory file. The inventory stays closed +// (0.4.0 clients must keep loading it), so new switches live here. A 0.4.0 client never reads this file. +// +// { "format": "mozak.settings/v1", +// "annotations": { "personalVaults": ["../obsidian"] }, (accepted, no effect since 0.5.0) +// "concurrency": { "rebase": false }, +// "indexRoots": [ { "path": "../vault/personal", "private": true }, { "path": "../vault/research" } ], +// "scopes": { "anpit": { "annotations": true, "concurrency": { "rebase": true } } }, +// "usageLog": false } +// +// One file per installation, never inside a scope folder: a scope folder can be a public repo. +// +// Only the keys this version understands are validated. Any other key is reported by `check` as +// settings-unknown-key and has no effect. + +import { existsSync, readFileSync } from "node:fs"; +import { dirname, join, resolve } from "node:path"; +import { DomainError } from "./errors.ts"; +import { realOrSelf } from "./paths.ts"; +import type { ScopeEntry, ScopeInventory } from "./scope-index.ts"; + +export const SETTINGS_FILE = "mozak-settings.json"; +export const SETTINGS_FORMAT = "mozak.settings/v1"; +const KNOWN_TOP = ["format", "annotations", "concurrency", "indexRoots", "scopes", "usageLog"]; +const KNOWN_SCOPE = ["annotations", "concurrency"]; + +export interface ConcurrencySettings { rebase?: boolean } +/** A folder that locator resolution searches. private: results carry path and title only, unless a call asks for more. */ +export interface IndexRoot { path: string; private: boolean } +export interface Settings { + path: string | null; + personalVaults: string[] | null; + concurrency: ConcurrencySettings; + /** null or absent: roots are derived from the inventory (locators.ts defaultIndexRoots). */ + indexRoots?: IndexRoot[] | null; + scopes: Record; + /** Counts-only usage log next to the inventory. Default off. */ + usageLog: boolean; + issues: { code: string; message: string }[]; +} + +const isPlain = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); + +/** Read settings for an inventory. Absent file: defaults. Invalid file: throws settings-invalid. */ +export function loadSettings(inv: ScopeInventory): Settings { + const inventoryPath = (inv as { path?: string }).path; + const empty: Settings = { path: null, personalVaults: null, concurrency: {}, indexRoots: null, scopes: {}, usageLog: false, issues: [] }; + if (!inventoryPath) return empty; + const path = join(dirname(inventoryPath), SETTINGS_FILE); + let text: string; + try { text = readFileSync(path, "utf8"); } + catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return empty; throw new DomainError("settings-invalid", `${path}: cannot read settings`, 2); } + const fail = (why: string): never => { throw new DomainError("settings-invalid", `${path}: ${why}`, 2); }; + let raw: unknown; + try { raw = JSON.parse(text); } catch { return fail("not valid JSON"); } + if (!isPlain(raw)) return fail("settings must be a JSON object"); + if (raw.format !== SETTINGS_FORMAT) fail(`format must be "${SETTINGS_FORMAT}"`); + const issues: Settings["issues"] = []; + for (const key of Object.keys(raw)) { + if (!KNOWN_TOP.includes(key)) issues.push({ code: "settings-unknown-key", message: `${SETTINGS_FILE}: unknown key "${key}" has no effect` }); + } + const concurrencyOf = (value: unknown, at: string): ConcurrencySettings => { + if (!isPlain(value)) return fail(`"${at}" must be an object`); + for (const key of Object.keys(value)) if (key !== "rebase") issues.push({ code: "settings-unknown-key", message: `${SETTINGS_FILE}: unknown key "${at}.${key}" has no effect` }); + if (value.rebase !== undefined && typeof value.rebase !== "boolean") fail(`${at}.rebase must be true or false`); + return value.rebase === undefined ? {} : { rebase: value.rebase as boolean }; + }; + const concurrency = raw.concurrency === undefined ? {} : concurrencyOf(raw.concurrency, "concurrency"); + let personalVaults: string[] | null = null; + if (raw.annotations !== undefined) { + if (!isPlain(raw.annotations)) fail(`"annotations" must be an object`); + const a = raw.annotations as Record; + for (const key of Object.keys(a)) if (key !== "personalVaults") issues.push({ code: "settings-unknown-key", message: `${SETTINGS_FILE}: unknown key "annotations.${key}" has no effect` }); + if (a.personalVaults !== undefined) { + if (!Array.isArray(a.personalVaults) || a.personalVaults.some((p) => typeof p !== "string" || !p.trim())) fail(`"annotations.personalVaults" must be an array of paths`); + personalVaults = (a.personalVaults as string[]).map((p) => realOrSelf(resolve(dirname(path), p))); + } + } + let indexRoots: IndexRoot[] | null = null; + if (raw.indexRoots !== undefined) { + if (!Array.isArray(raw.indexRoots)) fail(`"indexRoots" must be an array of { "path": ..., "private": true or false }`); + indexRoots = (raw.indexRoots as unknown[]).map((item, i) => { + if (!isPlain(item)) return fail(`indexRoots[${i}] must be an object`); + for (const key of Object.keys(item)) if (key !== "path" && key !== "private") issues.push({ code: "settings-unknown-key", message: `${SETTINGS_FILE}: unknown key "indexRoots[${i}].${key}" has no effect` }); + if (typeof item.path !== "string" || !item.path.trim()) fail(`indexRoots[${i}].path must be a non-empty path`); + if (item.private !== undefined && typeof item.private !== "boolean") fail(`indexRoots[${i}].private must be true or false`); + return { path: realOrSelf(resolve(dirname(path), item.path as string)), private: item.private === true }; + }); + } + const scopes: Settings["scopes"] = {}; + if (raw.scopes !== undefined) { + if (!isPlain(raw.scopes)) fail(`"scopes" must be an object keyed by scope id`); + for (const [id, value] of Object.entries(raw.scopes as Record)) { + if (!isPlain(value)) fail(`scopes.${id} must be an object`); + const v = value as Record; + for (const key of Object.keys(v)) if (!KNOWN_SCOPE.includes(key)) issues.push({ code: "settings-unknown-key", message: `${SETTINGS_FILE}: unknown key "scopes.${id}.${key}" has no effect` }); + if (v.annotations !== undefined && typeof v.annotations !== "boolean") fail(`scopes.${id}.annotations must be true or false`); + scopes[id] = { + ...(v.annotations === undefined ? {} : { annotations: v.annotations as boolean }), + ...(v.concurrency === undefined ? {} : { concurrency: concurrencyOf(v.concurrency, `scopes.${id}.concurrency`) }), + }; + if (!inv.scopes.some((s) => s.id === id)) issues.push({ code: "settings-unknown-scope", message: `${SETTINGS_FILE}: scope "${id}" is not in the inventory` }); + } + } + return { path, personalVaults, concurrency, indexRoots, scopes, usageLog: usageLogOf(raw.usageLog, fail), issues }; +} + +/** `usageLog`: absent is off, otherwise it must be a boolean. */ +function usageLogOf(value: unknown, fail: (why: string) => never): boolean { + if (value === undefined) return false; + return typeof value === "boolean" ? value : fail(`"usageLog" must be true or false`); +} + +/** + * Experimental read-set rebase for one scope (S1b). A per-scope `scopes..concurrency.rebase` wins over the + * top-level `concurrency.rebase`. Default off. An unreadable or invalid settings file keeps it off; `check` + * reports the file. + */ +export function rebaseEnabled(inv: ScopeInventory, scopeId: string): boolean { + let settings: Settings; + try { settings = loadSettings(inv); } + catch (e) { if (e instanceof DomainError) return false; throw e; } + return (settings.scopes[scopeId]?.concurrency?.rebase ?? settings.concurrency.rebase) === true; +} + +/** The `usageLog` setting. An unreadable or invalid settings file keeps it off; `check` reports the file. */ +export function usageLogSetting(inv: ScopeInventory): boolean { + try { return loadSettings(inv).usageLog; } + catch (e) { if (e instanceof DomainError) return false; throw e; } +} + +/** A mozak-settings.json inside a scope folder is never read. Returns its path when one exists, for `check`. */ +export function ignoredScopeSettingsFile(inv: ScopeInventory, entry: ScopeEntry): string | null { + const local = join(entry.root, SETTINGS_FILE); + if (!existsSync(local)) return null; + const inventoryPath = (inv as { path?: string }).path; + if (inventoryPath && realOrSelf(join(dirname(inventoryPath), SETTINGS_FILE)) === realOrSelf(local)) return null; + return local; +} + +export type AnnotationsMode = { enabled: true; source: "setting" } | { enabled: false; source: "setting" | "default" | "repo-mode" }; + +/** + * Whether owner annotations are on for a scope. Off by default (0.5.0): a scope without `scopes..annotations: true` + * behaves like 0.4.7, its sidecar is never read and `annotate` is refused. Repo-mode remote scopes are always refused: + * their plans are committed and pushed to a repository, which may be public. `annotations.personalVaults` is still + * accepted for older settings files and has no effect. + */ +export function annotationsMode(settings: Settings, entry: ScopeEntry): AnnotationsMode { + if (entry.remote && entry.remote.plansMode === "repo") return { enabled: false, source: "repo-mode" }; + const explicit = settings.scopes[entry.id]?.annotations; + if (explicit === true) return { enabled: true, source: "setting" }; + return { enabled: false, source: explicit === false ? "setting" : "default" }; +} + +/** annotationsMode for one scope of an inventory. An unreadable or invalid settings file keeps annotations off. */ +export function annotationsEnabled(inv: ScopeInventory, entry: ScopeEntry): boolean { + try { return annotationsMode(loadSettings(inv), entry).enabled; } + catch (e) { if (e instanceof DomainError) return false; throw e; } +} diff --git a/packages/core/src/similar.ts b/packages/core/src/similar.ts new file mode 100644 index 0000000..ca5fb61 --- /dev/null +++ b/packages/core/src/similar.ts @@ -0,0 +1,186 @@ +// `mozak similar` (D3 goal 1): an on-demand report of similar plans across one scope or every scope. No stored state, +// no model. It runs the propose guard's own rules (review.ts similarityMatch, the rules behind findSimilarPlans) on a +// pool of every plan, with Croatian diacritics folded, then drops templated siblings and labels what is left. +// Completed and rejected plans are in the pool, but a pair is reported only when at least one side is live (open, +// paused or awaiting): two finished or two rejected plans leave nothing to decide. +// +// Template filter: two plans with the same outcome-id list and fewer than 2 shared title tokens are siblings made +// from one template (two papers with the same outcomes), never a match. +// Labels: duplicate (same content, or most body words shared and every title word of each plan found in the other), +// supersedes-candidate (the newer plan names the older one, or the older one was rejected), overlap (anything else). +// Rejects whose reason says "moved to" are listed apart: those are moves between scopes, not duplicates. + +import { foldText, foldKey } from "./fold.ts"; +import { planDisplayState, type PlanDisplayState } from "./bridge.ts"; +import { similarityMatch, similarityProfile, type SimilarityProfile } from "./review.ts"; +import type { Plan, PlanContent, ScopeState } from "./understanding.ts"; + +export type SimilarLabel = "duplicate" | "supersedes-candidate" | "overlap"; + +export interface SimilarPlanRef { + scope: string; + planId: string; + title: string; + state: PlanDisplayState; + createdAt: string; +} + +export interface SimilarPair { + label: SimilarLabel; + /** For supersedes-candidate: the newer plan. Otherwise the first in scope/plan order. */ + a: SimilarPlanRef; + /** For supersedes-candidate: the older plan it may replace. */ + b: SimilarPlanRef; + rule: "same-content" | "title" | "id-and-title" | "id-and-body"; + /** Why the label was chosen, in one short sentence. */ + why: string; + titleShared: string[]; + bodyShared: string[]; + titleJaccard: number; + bodyJaccard: number; + sameContent: boolean; + crossScope: boolean; +} + +export interface MovedReject extends SimilarPlanRef { + reason: string; +} + +export interface SimilarReport { + plans: number; + comparedPairs: number; + templateFiltered: number; + pairs: SimilarPair[]; + moved: MovedReject[]; +} + +interface Pooled { + ref: SimilarPlanRef; + content: PlanContent; + digest: string; + profile: SimilarityProfile; + outcomeIds: string; + /** Folded, lowercased text of the plan's own words and sources, for id mentions. */ + mentionText: string; +} + +const DUPLICATE_BODY = 0.6; +const live = (s: PlanDisplayState) => s === "open" || s === "paused" || s === "awaiting"; + +function jaccard(a: string[], b: string[]): number { + if (!a.length && !b.length) return 1; + const sb = new Set(b); + const shared = a.filter((t) => sb.has(t)).length; + return shared / (new Set([...a, ...b]).size || 1); +} + +function contentOf(plan: Plan): { content: PlanContent; digest: string } | null { + const rev = plan.accepted ?? plan.pending; + return rev ? { content: rev.content, digest: rev.contentDigest } : null; +} + +function mentions(text: string, planId: string): boolean { + const id = foldKey(planId); + if (id.length < 4) return false; + const re = new RegExp(`(^|[^a-z0-9_-])${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^a-z0-9_-])`); + return re.test(text); +} + +function pool(scopes: { id: string; state: ScopeState }[]): { pooled: Pooled[]; moved: MovedReject[] } { + const pooled: Pooled[] = []; + const moved: MovedReject[] = []; + for (const { id: scope, state } of scopes) { + for (const plan of state.plans) { + const c = contentOf(plan); + if (!c) continue; + const ref: SimilarPlanRef = { scope, planId: plan.id, title: c.content.title, state: planDisplayState(plan), createdAt: plan.createdAt }; + if (ref.state === "rejected") { + const decision = plan.decisions.find((d) => d.id === plan.pending?.rejectionDecisionId); + if (decision && /\bmoved to\b/.test(foldKey(decision.reason))) moved.push({ ...ref, reason: decision.reason }); + } + const t = c.content; + pooled.push({ + ref, + content: t, + digest: c.digest, + profile: similarityProfile(plan.id, t, foldText), + outcomeIds: JSON.stringify(t.outcomes.map((o) => o.id).sort()), + mentionText: foldKey([t.purpose, t.rationale, ...t.sources.map((s) => `${s.locator} ${s.anchor ?? ""}`), ...t.constraints.map((x) => x.text)].join("\n")), + }); + } + } + return { pooled, moved }; +} + +const order = (x: SimilarPlanRef, y: SimilarPlanRef) => x.scope.localeCompare(y.scope) || x.planId.localeCompare(y.planId); + +/** Every title word of each plan appears somewhere in the other plan. A template sibling fails this on its subject name. */ +function titlesCovered(p: SimilarityProfile, q: SimilarityProfile): boolean { + const pb = new Set(p.body); + const qb = new Set(q.body); + return p.title.every((t) => qb.has(t)) && q.title.every((t) => pb.has(t)); +} + +function label(p: Pooled, q: Pooled, bodyJ: number): { label: SimilarLabel; a: Pooled; b: Pooled; why: string } { + const [first, second] = order(p.ref, q.ref) <= 0 ? [p, q] : [q, p]; + if (p.digest === q.digest) return { label: "duplicate", a: first, b: second, why: "same content" }; + if (bodyJ >= DUPLICATE_BODY && titlesCovered(p.profile, q.profile)) return { label: "duplicate", a: first, b: second, why: `nearly the same words (body ${bodyJ.toFixed(2)}), each title found in the other plan` }; + const newerFirst = Date.parse(p.ref.createdAt) >= Date.parse(q.ref.createdAt) ? [p, q] : [q, p]; + const [newer, older] = newerFirst as [Pooled, Pooled]; + if (mentions(newer.mentionText, older.ref.planId)) return { label: "supersedes-candidate", a: newer, b: older, why: `${newer.ref.planId} names ${older.ref.planId}` }; + if (older.ref.state === "rejected" && newer.ref.state !== "rejected") return { label: "supersedes-candidate", a: newer, b: older, why: `${older.ref.planId} was rejected and ${newer.ref.planId} is newer` }; + return { label: "overlap", a: first, b: second, why: "shared words, not the same plan" }; +} + +/** Pool every plan of the given scopes and report similar pairs. Pure: the caller reads the scopes. */ +export function similarReport(scopes: { id: string; state: ScopeState }[]): SimilarReport { + const { pooled, moved } = pool(scopes); + const pairs: SimilarPair[] = []; + let compared = 0; + let templateFiltered = 0; + for (let i = 0; i < pooled.length; i++) { + for (let j = i + 1; j < pooled.length; j++) { + const p = pooled[i]; + const q = pooled[j]; + if (!live(p.ref.state) && !live(q.ref.state)) continue; + compared++; + const sameContent = p.digest === q.digest; + const match = similarityMatch(p.profile, q.profile); + if (!match && !sameContent) continue; + if (!sameContent && match && p.outcomeIds === q.outcomeIds && match.titleShared.length < 2) { templateFiltered++; continue; } + const titleJ = jaccard(p.profile.title, q.profile.title); + const bodyJ = jaccard(p.profile.body, q.profile.body); + const l = label(p, q, bodyJ); + pairs.push({ + label: l.label, + a: l.a.ref, + b: l.b.ref, + rule: sameContent ? "same-content" : match!.rule, + why: l.why, + titleShared: match?.titleShared ?? p.profile.title, + bodyShared: match?.bodyShared ?? p.profile.body, + titleJaccard: Math.round(titleJ * 100) / 100, + bodyJaccard: Math.round(bodyJ * 100) / 100, + sameContent, + crossScope: p.ref.scope !== q.ref.scope, + }); + } + } + const rank: Record = { duplicate: 0, "supersedes-candidate": 1, overlap: 2 }; + pairs.sort((x, y) => rank[x.label] - rank[y.label] || order(x.a, y.a) || order(x.b, y.b)); + moved.sort(order); + return { plans: pooled.length, comparedPairs: compared, templateFiltered, pairs, moved }; +} + +/** Raw pooled lexical detector on every plan, without folding, live filter, template filter or labels: the baseline. */ +export function rawPooledPairs(scopes: { id: string; state: ScopeState }[]): number { + const all: { id: string; profile: SimilarityProfile }[] = []; + for (const { state } of scopes) for (const plan of state.plans) { + const c = contentOf(plan); + if (c) all.push({ id: plan.id, profile: similarityProfile(plan.id, c.content) }); + } + let n = 0; + for (let i = 0; i < all.length; i++) for (let j = i + 1; j < all.length; j++) if (similarityMatch(all[i].profile, all[j].profile)) n++; + return n; +} + diff --git a/packages/core/src/stale.ts b/packages/core/src/stale.ts deleted file mode 100644 index 1c040fa..0000000 --- a/packages/core/src/stale.ts +++ /dev/null @@ -1,221 +0,0 @@ -import { execFileSync } from "node:child_process"; -import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"; -import { basename, join, relative, sep } from "node:path"; -import { buildGraph, type LocalConfig } from "./graph.ts"; -import { scopeFile, isBridgeFileName } from "./scope-files.ts"; - -/** When something was last changed, derived from git. Nothing is stored, so there is no timestamp to forget to update. */ -export interface Touched { - /** Unix seconds, or null when nothing is known. */ - epoch: number | null; - /** commit: last commit. uncommitted: working tree is newer than the last commit. none: no git history. */ - source: "commit" | "uncommitted" | "none"; -} - -const NONE: Touched = { epoch: null, source: "none" }; -// Every dot folder (.git, the Obsidian config folder, ...) is skipped by the walk below as well. -const SKIP = new Set(["node_modules", "dist", "target"]); - -function git(root: string, args: string[]): string | null { - try { - return execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); - } catch { - return null; // not a repo, or git is missing - } -} - -export function gitRoot(dir: string): string | null { - const out = git(dir, ["rev-parse", "--show-toplevel"]); - return out ? realpathSync(out.trim()) : null; -} - -/** Paths with uncommitted changes (modified or untracked), relative to the repo root. */ -function dirtyPaths(root: string): string[] { - const out = git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]); - if (!out) return []; - const parts = out.split("\0").filter(Boolean); - const paths: string[] = []; - for (let i = 0; i < parts.length; i++) { - const entry = parts[i]; - paths.push(entry.slice(3)); - if (entry[0] === "R" || entry[0] === "C") i++; // renames carry the old path as the next field - } - return paths; -} - -/** Last change to a file or directory. A directory counts any file inside it. */ -export function touched(target: string): Touched { - if (!existsSync(target)) return NONE; - const real = realpathSync(target); - const root = gitRoot(statSync(real).isDirectory() ? real : join(real, "..")); - if (!root) return NONE; - const rel = relative(root, real) || "."; - const logged = git(root, ["log", "-1", "--format=%ct", "--", rel]); - const committed = logged && logged.trim() ? Number(logged.trim()) : null; - let dirty: number | null = null; - for (const p of dirtyPaths(root)) { - if (rel !== "." && p !== rel && !p.startsWith(rel + sep) && !p.startsWith(rel + "/")) continue; - try { - const m = Math.floor(statSync(join(root, p)).mtimeMs / 1000); - if (dirty === null || m > dirty) dirty = m; - } catch { - /* deleted file, no mtime to read */ - } - } - if (dirty !== null && (committed === null || dirty > committed)) return { epoch: dirty, source: "uncommitted" }; - return committed !== null ? { epoch: committed, source: "commit" } : NONE; -} - -export interface Upstream { - id: string; - /** How the scope relates to it, from this scope's point of view. */ - relation: string; - /** declared: this scope names it. reverse: it names this scope with informs or translates-to. */ - direction: "declared" | "reverse"; - touched: Touched; - /** Seconds newer than this scope, when it changed after it. */ - newerBy: number | null; -} - -export interface NoteChange { - name: string; - path: string; - touched: Touched; - newerBy: number | null; -} - -export interface StaleReport { - id: string; - kind: "project" | "topic"; - dir: string; - touched: Touched; - daysSinceTouched: number | null; - upstream: Upstream[]; - notes: NoteChange[]; - /** Links this scope declares upstream that do not resolve on this machine, so staleness cannot be judged. */ - unresolved: string[]; - verdict: "inputs-changed" | "no-input-changed" | "unknown"; -} - -export interface StaleOptions { - /** Only compare each scope's mozak.md, not every file in the scope. Quieter for busy code repos. */ - planOnly?: boolean; - now?: number; -} - -function mdFiles(dir: string, out: string[] = []): string[] { - let entries; - try { - entries = readdirSync(dir, { withFileTypes: true }); - } catch { - return out; - } - for (const e of entries) { - if (SKIP.has(e.name) || e.name.startsWith(".")) continue; - const p = join(dir, e.name); - if (e.isDirectory()) mdFiles(p, out); - else if (e.name.endsWith(".md")) out.push(p); - } - return out; -} - -function wikiNames(text: string): string[] { - const names = new Set(); - for (const m of text.matchAll(/\[\[([^\]|#\n]+)/g)) names.add(m[1].trim()); - return [...names]; -} - -/** For each scope (or one), say what changed after it was last touched. Read only. */ -export function staleReports(config: LocalConfig, only?: string, opts: StaleOptions = {}): StaleReport[] { - const now = opts.now ?? Math.floor(Date.now() / 1000); - const graph = buildGraph(config); - const byId = new Map(graph.nodes.map((n) => [n.id, n])); - const scopeTouched = (id: string): Touched => { - const n = byId.get(id); - if (!n) return NONE; - return touched(opts.planOnly ? scopeFile(n.dir, "bridge") : n.dir); - }; - const noteIndex = new Map>(); // repo root -> lowercase basename -> path - - const reports: StaleReport[] = []; - for (const node of graph.nodes) { - if (only && node.id !== only) continue; - const own = scopeTouched(node.id); - const newer = (t: Touched) => (own.epoch !== null && t.epoch !== null && t.epoch > own.epoch ? t.epoch - own.epoch : null); - - const upstream: Upstream[] = []; - const unresolved: string[] = []; - for (const e of graph.edges) { - if (e.from === node.id && (e.relation === "depends-on" || e.relation === "derived-from")) { - if (!e.to) { - unresolved.push(`${e.relation}: ${e.target}`); - continue; - } - const t = scopeTouched(e.to); - upstream.push({ id: e.to, relation: e.relation, direction: "declared", touched: t, newerBy: newer(t) }); - } else if (e.to === node.id && (e.relation === "informs" || e.relation === "translates-to")) { - const t = scopeTouched(e.from); - upstream.push({ id: e.from, relation: e.relation, direction: "reverse", touched: t, newerBy: newer(t) }); - } - } - - // Note level: wikilinks in this scope's own files that point at notes elsewhere in the same repo. - const notes: NoteChange[] = []; - const root = gitRoot(node.dir); - if (root) { - if (!noteIndex.has(root)) { - const idx = new Map(); - for (const f of mdFiles(root).sort()) { - const key = basename(f, ".md").toLowerCase(); - if (!idx.has(key)) idx.set(key, f); - } - noteIndex.set(root, idx); - } - const idx = noteIndex.get(root)!; - const seen = new Set(); - for (const f of mdFiles(node.dir)) { - if (isBridgeFileName(basename(f))) continue; - for (const name of wikiNames(readFileSync(f, "utf8"))) { - const target = idx.get(name.toLowerCase()); - if (!target || target.startsWith(node.dir + sep) || seen.has(target)) continue; - seen.add(target); - const t = touched(target); - notes.push({ name, path: target, touched: t, newerBy: newer(t) }); - } - } - } - - const changed = upstream.some((u) => u.newerBy !== null) || notes.some((n) => n.newerBy !== null); - reports.push({ - id: node.id, - kind: node.kind, - dir: node.dir, - touched: own, - daysSinceTouched: own.epoch === null ? null : Math.floor((now - own.epoch) / 86400), - upstream: upstream.sort((a, b) => a.id.localeCompare(b.id)), - notes: notes.sort((a, b) => a.name.localeCompare(b.name)), - unresolved, - verdict: own.epoch === null ? "unknown" : changed ? "inputs-changed" : "no-input-changed", - }); - } - return reports.sort((a, b) => a.id.localeCompare(b.id)); -} - -const day = (s: number) => new Date(s * 1000).toISOString().slice(0, 10); -const days = (s: number) => `+${Math.max(1, Math.round(s / 86400))}d`; - -export function renderStale(reports: StaleReport[]): string { - const out: string[] = []; - for (const r of reports) { - const when = r.touched.epoch === null ? "no git history" : `last touched ${day(r.touched.epoch)} (${r.daysSinceTouched}d ago, ${r.touched.source})`; - const flag = r.verdict === "inputs-changed" ? " [inputs changed]" : r.verdict === "unknown" ? " [unknown]" : ""; - out.push(`${r.id} (${r.kind}): ${when}${flag}`); - for (const u of r.upstream.filter((x) => x.newerBy !== null)) { - out.push(` ${u.id} ${u.direction === "declared" ? r.id + " " + u.relation : u.id + " " + u.relation + " " + r.id} changed ${day(u.touched.epoch!)} ${days(u.newerBy!)}`); - } - for (const n of r.notes.filter((x) => x.newerBy !== null)) out.push(` note [[${n.name}]] changed ${day(n.touched.epoch!)} ${days(n.newerBy!)}`); - for (const u of r.unresolved) out.push(` cannot judge, not found on this machine: ${u}`); - } - if (reports.some((r) => r.verdict === "inputs-changed")) out.push("\nChanged means a linked input was edited after this scope. It does not mean the edit matters."); - return out.join("\n"); -} diff --git a/packages/core/src/storage-hygiene.ts b/packages/core/src/storage-hygiene.ts index 0c4b76a..c48585b 100644 --- a/packages/core/src/storage-hygiene.ts +++ b/packages/core/src/storage-hygiene.ts @@ -3,7 +3,7 @@ import { appendFileSync, lstatSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { DomainError } from "./errors.ts"; -const IGNORE_PATTERNS = [".mozak-write-lock/", "mozak.json.*.tmp", "mozak.md.*.tmp", "MOZAK.json.*.tmp", "MOZAK.md.*.tmp"]; +const IGNORE_PATTERNS = [".mozak-write-lock/", "mozak.json.*.tmp", "mozak.md.*.tmp", "MOZAK.json.*.tmp", "MOZAK.md.*.tmp", "mozak.annotations.json.*.tmp"]; /** Only explicit init/repair writes these local rules. Never changes the git index. */ export function ensureStorageIgnored(root: string): void { diff --git a/packages/core/src/translate.ts b/packages/core/src/translate.ts deleted file mode 100644 index 0263fbc..0000000 --- a/packages/core/src/translate.ts +++ /dev/null @@ -1,83 +0,0 @@ -import type { MozakDoc } from "./parse.ts"; - -export interface TranslationDraft { - title: string; - /** Scope id the idea comes from. */ - source: string; - /** Scope id the idea moves into. */ - target: string; - /** Every assumption the idea rests on in the source. The caller must list them all. */ - assumptions: string[]; -} - -/** A new translation starts with every assumption open. It only becomes valid when the target re-derives each one. */ -export function renderTranslation(d: TranslationDraft): string { - if (!d.title.trim()) throw new Error("translation needs a title"); - if (d.assumptions.length === 0) throw new Error("translation needs at least one assumption, otherwise nothing is being re-derived"); - const lines = [`### ${d.title.trim()}`, `- source: [[${d.source}]]`, `- target: [[${d.target}]]`]; - for (const a of d.assumptions) lines.push(`- [open] ${a.trim()}`); - return lines.join("\n"); -} - -function titleOf(line: string): string | null { - const m = /^###\s+(.+?)\s*$/.exec(line); - return m ? m[1] : null; -} - -/** Append a translation block to the end of the Translations section. Refuses a duplicate title. */ -export function insertTranslation(text: string, block: string, title: string): string { - if (!/^## Translations\s*$/m.test(text)) throw new Error('mozak.md has no "## Translations" section'); - if (text.split(/\r?\n/).some((l) => titleOf(l) === title.trim())) throw new Error(`translation "${title}" already exists`); - return text.replace(/\s*$/, "\n") + "\n" + block + "\n"; -} - -/** Mark the nth (1 based) assumption of a translation as re-derived or open. */ -export function setAssumption(text: string, title: string, n: number, status: "re-derived" | "open"): string { - const lines = text.split(/\r?\n/); - const start = lines.findIndex((l) => titleOf(l) === title.trim()); - if (start < 0) throw new Error(`no translation titled "${title}"`); - let seen = 0; - for (let i = start + 1; i < lines.length; i++) { - if (/^##\s/.test(lines[i])) break; - const m = /^(\s*[-*]\s+)\[(re-derived|open)\](.*)$/.exec(lines[i]); - if (!m) continue; - if (++seen === n) { - lines[i] = `${m[1]}[${status}]${m[3]}`; - return lines.join("\n"); - } - } - throw new Error(`translation "${title}" has ${seen} assumptions, no number ${n}`); -} - -export interface Packet { - idea: string; - source: { id: string; kind: string; plan: string }; - target: { id: string; kind: string; plan: string }; - /** Existing declared relation between the two scopes, if any. */ - related: string[]; - assumptions: string[]; - draft: string; - instructions: string[]; -} - -/** Everything an agent needs to move one idea: both plans, how the scopes are already linked, and the draft block. */ -export function buildPacket(source: MozakDoc, target: MozakDoc, d: TranslationDraft): Packet { - const related = [ - ...source.links.filter((l) => l.target.includes(target.id)).map((l) => `${source.id} ${l.relation} ${target.id}`), - ...target.links.filter((l) => l.target.includes(source.id)).map((l) => `${target.id} ${l.relation} ${source.id}`), - ]; - return { - idea: d.title, - source: { id: source.id, kind: source.kind, plan: source.plan }, - target: { id: target.id, kind: target.kind, plan: target.plan }, - related, - assumptions: d.assumptions, - draft: renderTranslation(d), - instructions: [ - `For each assumption, check it in "${target.id}" itself. Do not carry the source's answer over.`, - "If it holds in the target, say what you observed and mark it [re-derived].", - "If it does not hold, replace it with the target's real assumption or drop the idea. Leave it [open].", - "A translation with any [open] assumption is invalid. It transfers no truth and no authority.", - ], - }; -} diff --git a/packages/core/src/usage.ts b/packages/core/src/usage.ts new file mode 100644 index 0000000..88a058f --- /dev/null +++ b/packages/core/src/usage.ts @@ -0,0 +1,145 @@ +// S2 usage log (Goal 5, local part). One JSON line per operation in /.mozak-cache/usage/, holding +// counts and codes only: operation, actor, scope id, exit code, status code, duration and output size. Never request +// bodies, prompts, plan text or ids of plans. The monthly aggregate is counts only, one file per host and month. +// Logging never changes an operation's result: every failure here is swallowed. + +import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { hostname } from "node:os"; +import { basename, dirname, join, resolve } from "node:path"; +import { DomainError } from "./errors.ts"; +import { replaceFileDurable } from "./durable.ts"; +import { isWithin, realOrSelf } from "./paths.ts"; +import { CACHE_DIR } from "./remote-meta.ts"; + +export const USAGE_DIR = "usage"; +export const USAGE_FORMAT = "mozak.usage/v1" as const; +export const AGGREGATE_FORMAT = "mozak.usage-aggregate/v1" as const; + +export interface UsageLine { + v: 1; ts: string; host: string; actor: string; op: string; + /** Selected scope id, "all" for all-scope reads, or null. */ + scope: string | null; + exit: number; status: string; ms: number; bytes: number; + committed?: boolean; rebased?: boolean; + /** Set when a locators call asked for private roots in full. */ + includePrivate?: boolean; +} + +/** Host name made safe for a file name. */ +export function usageHost(name = hostname()): string { + return name.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[.-]+/, "").slice(0, 64) || "host"; +} +export const monthOf = (d: Date) => d.toISOString().slice(0, 7); +export function usageDir(baseDir: string): string { return join(baseDir, CACHE_DIR, USAGE_DIR); } +export function usageLogPath(baseDir: string, month: string, host = usageHost()): string { return join(usageDir(baseDir), `${host}-${month}.jsonl`); } + +/** + * Opt-in. On when MOZAK_USAGE_LOG is "on", "1" or "true", or when the installation setting `usageLog` is true. + * An explicit "0", "off" or "false" wins over the setting. Anything else counts as unset. + */ +export function usageLogEnabled(env: NodeJS.ProcessEnv = process.env, setting = false): boolean { + const v = (env.MOZAK_USAGE_LOG ?? "").trim().toLowerCase(); + if (v === "on" || v === "1" || v === "true") return true; + if (v === "off" || v === "0" || v === "false") return false; + return setting; +} + +/** Append one line. Creates the folder with a `*` .gitignore so a cache inside a vault is never committed. */ +export function appendUsage(baseDir: string, line: UsageLine): boolean { + try { + const dir = usageDir(baseDir); + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true, mode: 0o700 }); + writeFileSync(join(dir, ".gitignore"), "*\n", { mode: 0o600 }); + } + appendFileSync(usageLogPath(baseDir, line.ts.slice(0, 7), line.host), `${JSON.stringify(line)}\n`, { mode: 0o600 }); + return true; + } catch { return false; } +} + +/** Build the line for one finished operation. Only fixed fields of the result envelope are read. */ +export function usageLine(operation: string, args: unknown, actor: string, data: Record, exitCode: number, ms: number, now = new Date()): UsageLine { + const a = args && typeof args === "object" && !Array.isArray(args) ? args as Record : {}; + const scope = typeof a.scope === "string" ? a.scope : a.all === true ? "all" : null; + let bytes = 0; + try { bytes = Buffer.byteLength(JSON.stringify(data)); } catch { /* size unknown */ } + return { + v: 1, ts: now.toISOString(), host: usageHost(), actor, op: operation, scope, exit: exitCode, + status: typeof data.status === "string" ? data.status : "unknown", ms: Math.max(0, Math.round(ms)), bytes, + ...(data.committed === true ? { committed: true } : {}), ...(data.rebased ? { rebased: true } : {}), + ...(a.includePrivate === true ? { includePrivate: true } : {}), + }; +} + +export function readUsageLines(baseDir: string, month: string, host = usageHost()): UsageLine[] { + let text = ""; + try { text = readFileSync(usageLogPath(baseDir, month, host), "utf8"); } catch { return []; } + const out: UsageLine[] = []; + for (const raw of text.split("\n")) { + if (!raw.trim()) continue; + try { + const l = JSON.parse(raw) as UsageLine; + if (l && l.v === 1 && typeof l.op === "string" && typeof l.ts === "string" && l.ts.startsWith(month)) out.push(l); + } catch { /* a torn last line from a crash is skipped */ } + } + return out; +} + +export interface UsageAggregate { + format: typeof AGGREGATE_FORMAT; host: string; month: string; + calls: number; writes: number; staleRefusals: number; rebased: number; + byOperation: Record; statuses: Record; msP50: number; msP95: number; bytesTotal: number }>; + byActor: Record; +} + +const pct = (sorted: number[], p: number) => (sorted.length ? sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)]! : 0); +const bump = (o: Record, k: string) => { o[k] = (o[k] ?? 0) + 1; }; + +/** Counts only: no scope ids, no timestamps finer than the month. */ +export function aggregateUsage(lines: UsageLine[], host: string, month: string): UsageAggregate { + const agg: UsageAggregate = { format: AGGREGATE_FORMAT, host, month, calls: 0, writes: 0, staleRefusals: 0, rebased: 0, byOperation: {}, byActor: {} }; + const ms = new Map(); + for (const l of lines) { + if (!l.ts.startsWith(month)) continue; + agg.calls++; + if (l.committed) agg.writes++; + if (l.status === "stale-input") agg.staleRefusals++; + if (l.rebased) agg.rebased++; + bump(agg.byActor, l.actor); + const op = (agg.byOperation[l.op] ??= { calls: 0, exits: {}, statuses: {}, msP50: 0, msP95: 0, bytesTotal: 0 }); + op.calls++; bump(op.exits, String(l.exit)); bump(op.statuses, l.status); op.bytesTotal += l.bytes || 0; + ms.set(l.op, [...(ms.get(l.op) ?? []), l.ms || 0]); + } + for (const [op, list] of ms) { const s = list.sort((x, y) => x - y); agg.byOperation[op]!.msP50 = pct(s, 50); agg.byOperation[op]!.msP95 = pct(s, 95); } + // Stable key order so the file diffs cleanly month to month. + agg.byOperation = Object.fromEntries(Object.entries(agg.byOperation).sort(([x], [y]) => (x < y ? -1 : 1))); + return agg; +} + +/** Resolve the existing ancestor too, so a new child of a symlinked scope cannot bypass overlap checks. */ +function realish(p: string): string { + const absolute = resolve(p); + if (existsSync(absolute)) return resolve(realOrSelf(absolute)); + const parent = dirname(absolute); + return parent === absolute ? absolute : join(realish(parent), basename(absolute)); +} + +/** + * Write `/-.json`. The design puts it at the personal vault root in `.mozak-usage/`, outside + * every scope and index root and never in a shared vault: callers pass those roots as `forbiddenRoots`. + */ +export function writeUsageAggregate(targetDir: string, agg: UsageAggregate, forbiddenRoots: string[] = []): string { + if (!/^\d{4}-\d{2}$/.test(agg.month)) throw new DomainError("invalid-input", "month must be yyyy-mm", 2); + const dir = realish(targetDir); + for (const root of forbiddenRoots) { + const r = realish(root); + if (isWithin(dir, r) || isWithin(r, dir)) throw new DomainError("usage-target-refused", `aggregates must live outside every scope and index root; ${targetDir} overlaps ${root}`, 2); + } + mkdirSync(dir, { recursive: true }); + const st = lstatSync(dir); + if (!st.isDirectory() || st.isSymbolicLink()) throw new DomainError("unsafe-path", `${targetDir} must be a regular folder`, 2); + const path = join(dir, `${usageHost(agg.host)}-${agg.month}.json`); + if (dirname(path) !== dir) throw new DomainError("unsafe-path", "aggregate path escapes its folder", 2); + replaceFileDurable(path, `${JSON.stringify(agg, null, 2)}\n`); + return path; +} diff --git a/packages/core/src/write.ts b/packages/core/src/write.ts deleted file mode 100644 index 0e4344f..0000000 --- a/packages/core/src/write.ts +++ /dev/null @@ -1,22 +0,0 @@ -import { createHash } from "node:crypto"; -import { readFileSync } from "node:fs"; -import { DomainError } from "./errors.ts"; - -export const hashText = (text: string): string => createHash("sha256").update(text).digest("hex"); -export const EMPTY_HASH = hashText(""); -export interface Snapshot { text: string; hash: string } -/** Legacy inspection helper only. Format-2 writers distinguish missing and empty files. */ -export function readSnapshot(path: string): Snapshot { - let text: string; - try { text = readFileSync(path, "utf8"); } - catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; text = ""; } - return { text, hash: hashText(text) }; -} -export interface LockOptions { timeoutMs?: number; staleMs?: number } -/** Retired path kept only to fail explicitly for old internal consumers. */ -export function guardedWrite(_path: string, _text: string, _baseHash: string, _opts: LockOptions = {}): never { - throw new DomainError("unsupported-legacy-operation", "raw Markdown writes are retired; use explicit format-2 plan operations"); -} -export function updateFile(_path: string, _transform: (text: string) => string, _opts: LockOptions & { retries?: number } = {}): never { - throw new DomainError("unsupported-legacy-operation", "raw transform writes are retired; use explicit format-2 plan operations"); -} diff --git a/packages/core/test/annotations-default.test.ts b/packages/core/test/annotations-default.test.ts new file mode 100644 index 0000000..843a700 --- /dev/null +++ b/packages/core/test/annotations-default.test.ts @@ -0,0 +1,82 @@ +// Owner annotations are off by default (owner decision for 0.5.0). A scope without the per-scope setting behaves like +// 0.4.7: the sidecar is never read, annotate is refused, and mozak.md does not change. Synthetic temp scopes only. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { ANNOTATIONS_FILE } from "../src/annotations.ts"; +import { annotationsMode, loadSettings } from "../src/settings.ts"; +import { loadScopesModel } from "../../obsidian/src/load.ts"; + +after(cleanup); +type Issue = { code: string; message: string }; +const ref = (planId: string, target: string) => ({ kind: "ref", planId, target, relation: "needs", evidence: `${planId} needs ${target} (synthetic).` }); + +/** Two plans in alpha, b needs a, written while annotations are on, then the setting is removed. */ +function annotatedThenDefault() { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a", { title: "Synthetic plan A" }); + w.propose("alpha", "b", { title: "Synthetic plan B" }); + assert.equal(w.annotate("alpha", [ref("b", "alpha/a"), { kind: "deadline", planId: "a", date: "2099-01-02", evidence: "Due 2099-01-02." }]).exitCode, 0); + const settings = join(w.base, "mozak-settings.json"); + return { w, settings, off: () => writeFileSync(settings, JSON.stringify({ format: "mozak.settings/v1" })) }; +} + +test("annotationsMode: off without a per-scope setting, also with personalVaults; on only when the scope turns it on", () => { + const w = world(["alpha", "beta"]); + const base = loadSettings(w.inv()); + assert.deepEqual(annotationsMode(base, w.entries.alpha), { enabled: false, source: "default" }); + assert.deepEqual(annotationsMode({ ...base, personalVaults: [w.entries.alpha.root] }, w.entries.alpha), { enabled: false, source: "default" }); + assert.deepEqual(annotationsMode({ ...base, scopes: { alpha: { annotations: true } } }, w.entries.alpha), { enabled: true, source: "setting" }); + assert.deepEqual(annotationsMode({ ...base, scopes: { alpha: { annotations: true } } }, w.entries.beta), { enabled: false, source: "default" }); +}); + +test("default scope: annotate is refused with annotations-disabled and nothing is written", () => { + const w = world(); + w.propose("alpha", "a"); w.propose("alpha", "b"); + const out = w.annotate("alpha", [ref("b", "alpha/a")]); + assert.equal(out.exitCode, 2); + assert.equal(out.data.status, "annotations-disabled"); + assert.match(String((out.data.issues as Issue[])[0]?.message), /mozak-settings\.json/); + assert.equal(w.token("alpha").exists, false); +}); + +test("default scope: an existing sidecar is not read by graph, ready, plans --sort deadline, check or the plugin", () => { + const { w, off } = annotatedThenDefault(); + const on = { graph: w.op("graph", { scope: "alpha" }).data.graph as { counts: { edges: number } }, sorted: w.op("plans", { scope: "alpha", sort: "deadline" }) }; + assert.equal(on.graph.counts.edges, 1, "sanity: the sidecar is read while annotations are on"); + off(); + assert.equal((w.op("graph", { scope: "alpha" }).data.graph as { counts: { edges: number } }).counts.edges, 0); + assert.deepEqual(w.op("graph", { scope: "alpha" }).data.annotations, { alpha: { exists: false, sha256: null } }); + const ready = w.op("ready", { scope: "alpha" }).data.ready as { ready: { planId: string }[]; blocked: unknown[] }; + assert.deepEqual(ready.ready.map((r) => r.planId).sort(), ["a", "b"]); + assert.deepEqual(ready.blocked, []); + const sorted = JSON.stringify(w.op("plans", { scope: "alpha", sort: "deadline" }).data); + assert.equal(sorted.includes("2099-01-02"), false); + writeFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE), "{ not json"); + const check = w.op("check", { scope: "alpha" }); + assert.equal((check.data.issues as Issue[]).some((i) => i.code.startsWith("annotation")), false, JSON.stringify(check.data.issues)); + const model = loadScopesModel(w.config); + assert.deepEqual(model.scopes[0]!.plans.map((p) => p.refs ?? []), [[], []]); +}); + +test("an invalid settings file keeps annotations off: graph ignores the sidecar, annotate reports settings-invalid", () => { + const { w, settings } = annotatedThenDefault(); + writeFileSync(settings, JSON.stringify({ format: "mozak.settings/v1", scopes: { alpha: { annotations: "yes" } } })); + assert.equal((w.op("graph", { scope: "alpha" }).data.graph as { counts: { edges: number } }).counts.edges, 0); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).data.status, "settings-invalid"); +}); + +test("default scope: mozak.md is byte-identical with and without a sidecar, and render leaves it alone", () => { + const { w, off } = annotatedThenDefault(); + off(); + const withSidecar = readFileSync(join(w.entries.alpha.root, "mozak.md")); + assert.equal(w.op("render", { scope: "alpha" }).exitCode, 0); + assert.deepEqual(readFileSync(join(w.entries.alpha.root, "mozak.md")), withSidecar); + writeFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE), "{}"); + w.propose("alpha", "c", {}, false); + const after = readFileSync(join(w.entries.alpha.root, "mozak.md"), "utf8"); + assert.equal(after.includes("2099-01-02"), false); + assert.equal(after.includes("needs"), false); +}); diff --git a/packages/core/test/annotations-fixture.ts b/packages/core/test/annotations-fixture.ts new file mode 100644 index 0000000..e3fddcf --- /dev/null +++ b/packages/core/test/annotations-fixture.ts @@ -0,0 +1,87 @@ +// Synthetic temp scopes for annotation tests. Never touches a real inventory or vault. +import { execFileSync } from "node:child_process"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { initScopeState, mutateScope, readScope } from "../src/scope-store.ts"; +import { reviewShow } from "../src/review.ts"; +import { executeOperation } from "../src/api.ts"; +import { loadInventory } from "../src/scope-index.ts"; +import { readAnnotations } from "../src/annotations.ts"; + +export const NOW = "2026-10-20T09:00:00.000Z"; +const roots: string[] = []; +export function cleanup() { for (const r of roots.splice(0)) rmSync(r, { recursive: true, force: true }); } + +export interface PlanSpec { title?: string; purpose?: string; rationale?: string; outcomes?: { id: string; statement?: string; criterion?: string }[]; constraints?: string[] } +// Keys in sorted order on purpose: pendingChangedFields sorts the changed fields, and a re-read state has +// sorted keys, so sorted content renders the same before and after a reread. +export const content = (id: string, spec: PlanSpec = {}) => ({ + constraints: (spec.constraints ?? []).map((text, i) => ({ id: `c${i + 1}`, text })), + nonGoals: [], + outcomes: (spec.outcomes ?? [{ id: "done" }]).map((o) => ({ acceptance: "objective", criterion: o.criterion ?? "Synthetic check passes", id: o.id, statement: o.statement ?? `Outcome ${o.id} of ${id}` })), + purpose: spec.purpose ?? `Exercise synthetic plan ${id}`, + questions: [], + rationale: spec.rationale ?? `Synthetic rationale for ${id}`, + sources: [], + title: spec.title ?? `Synthetic ${id} work`, +}); + +export function world(scopeIds: string[] = ["alpha"], options: { git?: boolean; settings?: Record; annotations?: boolean } = {}) { + const base = mkdtempSync(join(process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(), "mozak-annot-")); + roots.push(base); + const entries: Record = {}; + for (const id of scopeIds) { + const root = join(base, id); + mkdirSync(root); + if (options.git) execFileSync("git", ["init", "-q", root], { timeout: 5000 }); + writeFileSync(join(root, "README.md"), "Synthetic scope\n"); + writeFileSync(join(root, "AGENTS.md"), "Synthetic instructions\n"); + entries[id] = { id, root }; + initScopeState(entries[id], { operationId: `init-${id}`, scopeId: id, kind: "project", title: `Synthetic ${id}`, expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic:init", ownerMessageAt: NOW }); + } + const config = join(base, "inventory.json"); + writeFileSync(config, JSON.stringify({ format: "mozak.local/v3", scopes: scopeIds.map((id) => ({ id, root: entries[id].root })) })); + // annotations: true turns owner annotations on for every scope of this world (they are off by default). + const enable = options.annotations ? { format: "mozak.settings/v1", scopes: Object.fromEntries(scopeIds.map((id) => [id, { annotations: true }])) } : undefined; + const settings = enable && options.settings ? { ...options.settings, scopes: { ...enable.scopes, ...(options.settings.scopes as object ?? {}) } } : options.settings ?? enable; + if (settings !== undefined) writeFileSync(join(base, "mozak-settings.json"), JSON.stringify(settings)); + let seq = 0; + const inv = () => loadInventory(config); + const change = (scope: string, action: string, payload: unknown, actor: "agent" | "owner" = "agent") => + mutateScope(entries[scope], { operationId: `op-${++seq}`, scopeId: scope, expected: readScope(entries[scope]).snapshot, action, payload }, actor); + const plan = (scope: string, planId: string) => readScope(entries[scope]).state.plans.find((p) => p.id === planId)!; + const approve = (scope: string, planId: string) => { + const shown = reviewShow(readScope(entries[scope]).state, planId, "approve-direction"); + return change(scope, "approve-direction", { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: `synthetic:approve-${++seq}`, ownerMessageAt: NOW, reason: "Synthetic approval" }, "owner"); + }; + const propose = (scope: string, planId: string, spec: PlanSpec = {}, accept = true) => { + change(scope, "propose", { planId, content: content(planId, spec), distinctFromPlanIds: readScope(entries[scope]).state.plans.map((p) => p.id) }); + if (accept) approve(scope, planId); + }; + const reject = (scope: string, planId: string) => { + const shown = reviewShow(readScope(entries[scope]).state, planId, "reject-pending"); + return change(scope, "reject-pending", { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: `synthetic:reject-${++seq}`, ownerMessageAt: NOW, reason: "Synthetic rejection" }, "owner"); + }; + const pass = (scope: string, planId: string, outcomeId: string) => { + const p = plan(scope, planId); + const id = `obs-${++seq}`; + const evidence = { id: `${id}-e`, locator: "synthetic.ts", anchor: null, version: null, inspectedAt: NOW, activity: { kind: "run", description: "synthetic" }, result: { verdict: "pass", summary: "passed" }, limitations: [] }; + return change(scope, "observe", { planId, observation: { id, classification: "observed", summary: id, evidence: [evidence] }, reasoningLinks: [{ id: `${id}-link`, relation: "supports", from: { planId, revisionId: null, kind: "observation", id }, to: { planId, revisionId: p.accepted!.id, kind: "outcome", id: outcomeId }, rationale: "synthetic" }] }); + }; + const complete = (scope: string, planId: string) => { + for (const o of plan(scope, planId).accepted!.content.outcomes) pass(scope, planId, o.id); + return change(scope, "complete", { planId, revisionId: plan(scope, planId).accepted!.id }); + }; + const merge = (scope: string, target: string, source: string) => { + const t = plan(scope, target); + change(scope, "revise", { planId: target, acceptedRevisionId: t.accepted?.id ?? null, pendingRevisionId: t.pending?.id ?? null, mergeFromPlanId: source, content: content(target, { title: `Unified ${target}` }) }); + return approve(scope, target); + }; + const token = (scope: string) => readAnnotations(entries[scope].root).token; + const annotate = (scope: string, items: unknown[], extra: Record = {}, actor: "owner" | "agent" = "owner") => + executeOperation(inv(), "annotate", { scope, request: { operationId: `annot-${++seq}`, scopeId: scope, expectedAnnotations: token(scope), ownerRef: "synthetic:owner-message", ownerMessageAt: NOW, items, ...extra } }, actor); + const bytes = (scope: string) => ["mozak.json", "mozak.md"].map((n) => readFileSync(join(entries[scope].root, n))); + const op = (operation: string, args: Record) => executeOperation(inv(), operation, args); + return { base, config, entries, inv, change, plan, approve, propose, reject, pass, complete, merge, token, annotate, bytes, op }; +} diff --git a/packages/core/test/annotations.test.ts b/packages/core/test/annotations.test.ts new file mode 100644 index 0000000..ace2564 --- /dev/null +++ b/packages/core/test/annotations.test.ts @@ -0,0 +1,160 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, NOW, world } from "./annotations-fixture.ts"; +import { readScope, mutateScope } from "../src/scope-store.ts"; +import { itemDigest, proposeItems, readAnnotations, validateItem, ANNOTATIONS_FILE } from "../src/annotations.ts"; +import { leftoverTempFiles } from "../src/durable.ts"; +import { annotationsMode } from "../src/settings.ts"; +import { executeOperation } from "../src/api.ts"; + +after(cleanup); + +const ref = (planId: string, target: string, relation = "needs", extra: Record = {}) => ({ kind: "ref", planId, target, relation, evidence: `${planId} ${relation} ${target} (synthetic sentence).`, ...extra }); +type Issue = { code: string; message: string }; + +test("annotate writes only the sidecar: mozak.json and mozak.md stay byte-identical and the graph snapshot is unchanged", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + const before = w.bytes("alpha"); + const snapshot = readScope(w.entries.alpha).snapshot; + const out = w.annotate("alpha", [ref("a", "alpha/b"), { kind: "deadline", planId: "b", date: "2099-03-01", evidence: "Synthetic due 2099-03-01." }]); + assert.equal(out.exitCode, 0, JSON.stringify(out.data)); + assert.equal(out.data.status, "ok"); + assert.deepEqual(w.bytes("alpha"), before); + assert.deepEqual(readScope(w.entries.alpha).snapshot, snapshot); + const doc = readAnnotations(w.entries.alpha.root, "alpha").doc!; + assert.equal(doc.plans.a.refs.length, 1); + assert.equal(doc.plans.a.refs[0].provenance.ownerRef, "synthetic:owner-message"); + assert.equal(doc.plans.b.deadline!.date, "2099-03-01"); + assert.deepEqual((out.data.annotations as { exists: boolean }).exists, true); + // Only the sidecar appeared; no temp file is left behind. + assert.deepEqual(readdirSync(w.entries.alpha.root).filter((n) => n.startsWith("mozak")).sort(), ["mozak.annotations.json", "mozak.json", "mozak.md"]); +}); + +test("an agent snapshot taken before an annotation still writes: annotations never make agents stale", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + const snapshot = readScope(w.entries.alpha).snapshot; + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).exitCode, 0); + const result = mutateScope(w.entries.alpha, { operationId: "agent-after-annotate", scopeId: "alpha", expected: snapshot, action: "propose", payload: { planId: "c", content: { title: "Unrelated synthetic c", purpose: "p", outcomes: [{ id: "o", statement: "s", acceptance: "objective", criterion: "c" }], constraints: [], nonGoals: [], rationale: "r", questions: [], sources: [] } } }, "agent"); + assert.equal(result.committed, true); +}); + +test("annotate CAS: a stale sidecar token is refused with nothing written; replay returns the receipt; reuse with other input conflicts", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); w.propose("alpha", "c"); + const stale = w.token("alpha"); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).exitCode, 0); + const sidecar = readFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE)); + const refused = w.annotate("alpha", [ref("a", "alpha/c")], { expectedAnnotations: stale }); + assert.equal(refused.exitCode, 3); + assert.equal(refused.data.status, "stale-input"); + assert.deepEqual(readFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE)), sidecar); + const request = { operationId: "fixed-op", scopeId: "alpha", expectedAnnotations: w.token("alpha"), ownerRef: "synthetic:owner", ownerMessageAt: NOW, items: [ref("a", "alpha/c")] }; + const exec = (r: unknown) => executeOperation(w.inv(), "annotate", { scope: "alpha", request: r }, "owner"); + assert.equal(exec(request).exitCode, 0); + const again = exec(request); + assert.equal(again.exitCode, 0); + assert.equal(again.data.status, "replayed"); + const conflict = exec({ ...request, items: [ref("b", "alpha/c")] }); + assert.equal(conflict.exitCode, 3); + assert.equal(conflict.data.status, "operation-conflict"); +}); + +test("annotate is owner-only and agent attempts touch nothing", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + const out = w.annotate("alpha", [ref("a", "alpha/b")], {}, "agent"); + assert.equal(out.exitCode, 2); + assert.equal(out.data.status, "not-permitted"); + assert.equal(w.token("alpha").exists, false); +}); + +test("annotate refuses dangling targets, self references, unknown outcomes, digest mismatches and batches over 7", () => { + const w = world(["alpha", "beta"], { annotations: true }); + w.propose("alpha", "a", { outcomes: [{ id: "first" }] }); w.propose("alpha", "b"); + const cases: [unknown[], string][] = [ + [[ref("a", "alpha/missing")], "ref-dangling"], + [[ref("a", "beta/missing")], "ref-dangling"], + [[ref("a", "gamma/b")], "ref-dangling"], + [[ref("a", "alpha/b#nope")], "ref-dangling"], + [[ref("a", "alpha/a")], "invalid-input"], + [[ref("a", "alpha/b", "needs", { fromOutcome: "nope" })], "stale-reference"], + [[ref("ghost", "alpha/b")], "stale-reference"], + [[ref("a", "alpha/b", "blocks")], "invalid-input"], + [[{ ...ref("a", "alpha/b"), itemDigest: "0".repeat(64) }], "item-digest-mismatch"], + [Array.from({ length: 8 }, () => ref("a", "alpha/b")), "invalid-input"], + [[{ kind: "deadline", planId: "a", date: "2026-02-30", evidence: "x" }], "invalid-input"], + ]; + for (const [items, code] of cases) { + const out = w.annotate("alpha", items); + assert.equal(out.data.status, code, JSON.stringify(items)); + assert.equal(w.token("alpha").exists, false); + } + const item = validateItem(ref("a", "alpha/b#done")); + assert.equal(w.annotate("alpha", [{ ...item, itemDigest: itemDigest(item) }]).exitCode, 0); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b#done")]).data.status, "duplicate-ref"); +}); + +test("proposals carry one digest per item, at most seven, and never write", () => { + const items = proposeItems([ref("a", "alpha/b"), { kind: "deadline", planId: "a", date: "2099-01-01", evidence: "Due 2099-01-01." }]).items; + assert.equal(items.length, 2); + assert.match(items[0].itemDigest, /^[a-f0-9]{64}$/); + assert.notEqual(items[0].itemDigest, items[1].itemDigest); + assert.throws(() => proposeItems(Array.from({ length: 8 }, () => ref("a", "alpha/b"))), { code: "invalid-input" }); +}); + +test("settings: per-scope switch, personalVaults has no effect, repo-mode refusal", () => { + const w = world(["alpha", "beta"], { settings: { format: "mozak.settings/v1", scopes: { alpha: { annotations: true }, beta: { annotations: false } } } }); + w.propose("beta", "a"); w.propose("beta", "b"); + const out = w.annotate("beta", [ref("a", "beta/b")]); + assert.equal(out.data.status, "annotations-disabled"); + assert.equal(w.token("beta").exists, false); + const settings = { path: null, personalVaults: [w.entries.alpha.root], concurrency: {}, scopes: {}, usageLog: false, issues: [] }; + assert.deepEqual(annotationsMode(settings, w.entries.alpha), { enabled: false, source: "default" }); + assert.deepEqual(annotationsMode({ ...settings, scopes: { alpha: { annotations: true } } }, w.entries.alpha), { enabled: true, source: "setting" }); + assert.deepEqual(annotationsMode({ ...settings, scopes: { beta: { annotations: false } } }, w.entries.beta), { enabled: false, source: "setting" }); + const repo = { id: "r", root: w.entries.alpha.root, remote: { spec: "github:o/r", url: "", ref: "main", repoName: "r", baseDir: w.base, cacheRoot: "", fullClone: null, plansMode: "repo" as const } }; + assert.deepEqual(annotationsMode({ ...settings, scopes: { r: { annotations: true } } }, repo), { enabled: false, source: "repo-mode" }); + const vault = { ...repo, remote: { ...repo.remote, plansMode: "vault" as const } }; + assert.deepEqual(annotationsMode({ ...settings, scopes: { r: { annotations: true } } }, vault), { enabled: true, source: "setting" }); + assert.deepEqual(annotationsMode(settings, vault), { enabled: false, source: "default" }); +}); + +test("settings: invalid file refuses annotate; unknown keys are check findings", () => { + const w = world(["alpha"], { settings: { format: "mozak.settings/v1", scopes: { alpha: { annotations: "yes" } } } }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).data.status, "settings-invalid"); + writeFileSync(join(w.base, "mozak-settings.json"), JSON.stringify({ format: "mozak.settings/v1", typo: 1, concurrency: { rebase: false } })); + const check = w.op("check", { scope: "alpha" }); + const codes = (check.data.issues as Issue[]).map((i) => i.code); + assert.deepEqual(codes.filter((c) => c.startsWith("settings")), ["settings-unknown-key"]); +}); + +test("P0.5 extended: annotation temp files are ignored by git, reported by check and removed by the next write", () => { + const w = world(["alpha"], { git: true, annotations: true }); + w.propose("alpha", "a"); + const ignore = readFileSync(join(w.entries.alpha.root, ".gitignore"), "utf8"); + assert.match(ignore, /^mozak\.annotations\.json\.\*\.tmp$/m); + const stray = "mozak.annotations.json.0f8fad5b-d9cb-469f-a165-70867728950e.tmp"; + assert.equal(execFileSync("git", ["check-ignore", "--no-index", "--", stray], { cwd: w.entries.alpha.root, encoding: "utf8", timeout: 5000 }).trim(), stray); + writeFileSync(join(w.entries.alpha.root, stray), "partial"); + assert.deepEqual(leftoverTempFiles(w.entries.alpha.root), [stray]); + assert.ok((w.op("check", { scope: "alpha" }).data.issues as Issue[]).some((i) => i.code === "leftover-temp-file" && i.message.includes(stray))); + w.propose("alpha", "b", {}, false); + assert.deepEqual(leftoverTempFiles(w.entries.alpha.root), []); +}); + +test("a broken sidecar is reported by check and blocks annotate, but never hides plans", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + writeFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE), "{ not json"); + const check = w.op("check", { scope: "alpha" }); + assert.equal(check.exitCode, 3); + assert.ok((check.data.issues as Issue[]).some((i) => i.code === "annotations-invalid")); + assert.equal((w.op("context", { scope: "alpha" }).data.context as { plans: unknown[] }).plans.length, 2); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).data.status, "annotations-invalid"); +}); diff --git a/packages/core/test/deadlines.test.ts b/packages/core/test/deadlines.test.ts new file mode 100644 index 0000000..e9585a4 --- /dev/null +++ b/packages/core/test/deadlines.test.ts @@ -0,0 +1,137 @@ +// Deadline-from-prose rule (D3 Q19). Synthetic sentences only. Precision target: at least 0.9 on multi-date text. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { cuedDates, deadlineCandidates, planDeadline, sentences } from "../src/deadlines.ts"; +import { readScope } from "../src/scope-store.ts"; +import { readAnnotations } from "../src/annotations.ts"; +import { cleanup, world } from "./annotations-fixture.ts"; + +after(cleanup); +const DAY = "2026-10-21"; + +test("formats: ISO, D Mon YYYY, D. M. YYYY., D. YYYY., with optional weekday and colon", () => { + const cases: [string, string[]][] = [ + ["Submit by 2026-11-01.", ["2026-11-01"]], + ["Deadline is 1 Nov 2026 for the form.", ["2026-11-01"]], + ["Deadline: 3 December 2026.", ["2026-12-03"]], + ["Due Friday, 6 Nov 2026.", ["2026-11-06"]], + ["Rok je 1. 11. 2026. za prijavu.", ["2026-11-01"]], + ["Prijava do petka, 6. studenoga 2026.", ["2026-11-06"]], + ["Predati prije 15. siječnja 2027.", ["2027-01-15"]], + ["Rok: 2.3.2027.", ["2027-03-02"]], + ["Until Mon 30 Nov 2026 only.", ["2026-11-30"]], + ["Finish before 31 Mar 2027 and by 2027-04-15.", ["2027-03-31", "2027-04-15"]], + ]; + for (const [text, dates] of cases) assert.deepEqual(cuedDates(text).map((h) => h.date), dates, text); +}); + +test("no cue, no year, impossible days and glued words give no date", () => { + for (const text of [ + "Meeting on 2026-11-01 with the team.", + "Started 1 Nov 2026.", + "Submit by 1 Nov.", + "Rok je 1. 11.", + "Due 2026-02-30.", + "Nearby 2026-11-01 records.", + "Sastanak 5. studenoga 2026.", + "Deadline is soon, maybe 2026-12-01.", + "Odobreno 2026-11-01, rok uskoro.", + ]) assert.deepEqual(cuedDates(text), [], text); +}); + +test("sentences keep Croatian dates whole", () => { + assert.deepEqual(sentences("Rok je 1. 11. 2026. Druga rečenica do 3. studenoga 2026. Kraj."), ["Rok je 1. 11. 2026.", "Druga rečenica do 3. studenoga 2026.", "Kraj."]); +}); + +/** Each sentence holds at least two dates. Gold lists the dates a careful reader would call a deadline. */ +const LABELED: [string, string[]][] = [ + ["Kickoff was on 2026-09-01; the report is due 2026-11-15.", ["2026-11-15"]], + ["We met on 12 Oct 2026 and agreed to submit by 1 Nov 2026.", ["2026-11-01"]], + ["Data from 2026-01-01 to 2026-06-30 is in scope; deadline is 2026-12-01.", ["2026-12-01"]], + ["The call opened 1 Oct 2026 and closes, deadline 21 Oct 2026, with results on 15 Dec 2026.", ["2026-10-21"]], + ["Draft by 2026-11-10, final by 2026-11-30.", ["2026-11-10", "2026-11-30"]], + ["Interview scheduled 2026-11-03; references due 2026-11-01.", ["2026-11-01"]], + ["Natječaj je otvoren od 1. 10. 2026., rok je 31. 10. 2026.", ["2026-10-31"]], + ["Sastanak je bio 5. listopada 2026., prijavu predati do 20. studenoga 2026.", ["2026-11-20"]], + ["Prijave prije 1. prosinca 2026., rezultati 15. siječnja 2027.", ["2026-12-01"]], + ["Ugovor potpisan 2026-03-01, rok je 2026-12-31.", ["2026-12-31"]], + ["Version 1 shipped 3 Mar 2026; version 2 is due 3 Mar 2027.", ["2027-03-03"]], + ["Funding starts 2027-01-01 if we apply before 2026-11-20.", ["2026-11-20"]], + ["The grant runs 2027-01-01 to 2027-12-31; apply by 2026-11-01.", ["2026-11-01"]], + ["Trip on 4 Dec 2026, book tickets by 20 Nov 2026.", ["2026-11-20"]], + ["Registered 2026-02-02, renewal due 2027-02-02.", ["2027-02-02"]], + ["Do 15. 11. 2026. poslati sažetak, konferencija je 10. 12. 2026.", ["2026-11-15"]], + ["Rok je petak, 13. 11. 2026.; obrana 4. 12. 2026.", ["2026-11-13"]], + ["Recorded 2026-05-05 and 2026-06-06; nothing is due.", []], + ["Exam on 2027-01-20, register until 2027-01-10.", ["2027-01-10"]], + ["The review was moved from 2026-11-02 to 2026-11-09, slides due 2026-11-05.", ["2026-11-05"]], + ["Papers accepted 1 Feb 2027 will be presented 1 Jun 2027; camera ready by 1 Mar 2027.", ["2027-03-01"]], + ["Applications open 2026-11-01; deadline is Monday, 30 Nov 2026.", ["2026-11-30"]], + ["Beta 2026-12-01, GA 2027-02-01, freeze before 2027-01-15.", ["2027-01-15"]], + ["The offer letter dated 2026-10-01 must be signed by 2026-10-30.", ["2026-10-30"]], + ["Termin 3. studenoga 2026., materijali prije 1. studenoga 2026.", ["2026-11-01"]], + ["Projekt traje od 1. 1. 2027. do 31. 12. 2027.", ["2027-12-31"]], + ["Data collected until 2026-11-15 is used; submit by 2026-12-01.", ["2026-12-01"]], + ["Hearing on 9 Nov 2026, written answer due 2 Nov 2026.", ["2026-11-02"]], + ["Paid 2026-07-01, next invoice due 2026-12-01.", ["2026-12-01"]], + ["Phase one ended 2026-06-30; phase two must finish by 2027-06-30.", ["2027-06-30"]], +]; + +test("deadline rule precision on synthetic multi-date sentences is at least 0.9", (t) => { + let extracted = 0, correct = 0, gold = 0, found = 0; + for (const [text, labels] of LABELED) { + const dates = [...new Set(cuedDates(text).map((h) => h.date))]; + extracted += dates.length; + correct += dates.filter((d) => labels.includes(d)).length; + gold += labels.length; + found += labels.filter((d) => dates.includes(d)).length; + } + const precision = correct / extracted, recall = found / gold; + t.diagnostic(`deadline rule: ${LABELED.length} sentences, extracted ${extracted}, correct ${correct}, precision ${precision.toFixed(3)}, recall ${recall.toFixed(3)}`); + assert.ok(precision >= 0.9, `precision ${precision}`); +}); + +test("plan deadlines: one future date is inferred, several are candidates, past dates and done outcomes drop, owner wins", (t) => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "single", { purpose: "Submit the synthetic application by 2026-11-01. It was drafted on 2026-09-01." }); + w.propose("alpha", "several", { purpose: "Synthetic call, deadline 21 Oct 2026.", constraints: ["The second round is due 31 Mar 2027."] }); + w.propose("alpha", "past", { purpose: "Synthetic form was due 2026-01-10, and the next one is due 2026-12-05." }); + w.propose("alpha", "doneout", { outcomes: [{ id: "first", statement: "Send the synthetic draft by 2026-11-10." }, { id: "second", statement: "Send the synthetic final by 2026-12-10." }] }); + w.propose("alpha", "owner", { purpose: "Synthetic options: by 2026-11-11 or by 2026-12-12." }); + w.pass("alpha", "doneout", "first"); + assert.equal(w.annotate("alpha", [{ kind: "deadline", planId: "owner", date: "2026-12-12", evidence: "Owner picked 12 Dec 2026." }]).exitCode, 0); + const state = readScope(w.entries.alpha).state; + const doc = readAnnotations(w.entries.alpha.root, "alpha").doc; + const of = (id: string) => planDeadline(state, state.plans.find((p) => p.id === id)!, doc, DAY); + assert.deepEqual(of("single"), { status: "inferred", date: "2026-11-01", evidence: "Submit the synthetic application by 2026-11-01.", field: "purpose" }); + const several = of("several"); + assert.equal(several.status, "candidates"); + assert.deepEqual(several.status === "candidates" && several.candidates.map((c) => c.date), ["2026-10-21", "2027-03-31"]); + assert.equal(of("past").status, "inferred"); + assert.equal((of("past") as { date: string }).date, "2026-12-05"); + assert.equal((of("doneout") as { date: string }).date, "2026-12-10"); + assert.deepEqual(of("owner"), { status: "owner", date: "2026-12-12", evidence: "Owner picked 12 Dec 2026." }); + w.complete("alpha", "single"); + const after = readScope(w.entries.alpha).state; + assert.deepEqual(deadlineCandidates(after, after.plans.find((p) => p.id === "single")!, DAY), []); + const plans = state.plans.filter((p) => p.id !== "owner"); + const sent = plans.filter((p) => planDeadline(state, p, null, DAY).status === "candidates").length; + t.diagnostic(`plans with dates: ${plans.length}, sent to owner as candidates: ${sent}`); +}); + +test("plans --sort deadline orders rows by owner or inferred deadline and adds deadline fields", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "none"); + w.propose("alpha", "later", { purpose: "Synthetic, due 2099-06-01." }); + w.propose("alpha", "sooner", { purpose: "Synthetic, due 2099-02-01." }); + const sorted = w.op("plans", { scope: "alpha", sort: "deadline", limit: 2 }); + assert.equal(sorted.exitCode, 0); + const open = (sorted.data.groups as Record).open; + assert.deepEqual(open.rows.map((r) => [r.planId, r.deadline]), [["sooner", "2099-02-01"], ["later", "2099-06-01"]]); + const next = w.op("plans", { continuation: open.continuation }); + assert.equal(next.exitCode, 0); + assert.deepEqual((next.data.groups as Record).open.rows.map((r) => r.planId), ["none"]); + const plain = w.op("plans", { scope: "alpha" }); + assert.equal("deadline" in (plain.data.groups as Record).open.rows[0]!, false); + assert.equal(w.op("plans", { scope: "alpha", sort: "title" }).exitCode, 2); +}); diff --git a/packages/core/test/docs-links.test.ts b/packages/core/test/docs-links.test.ts new file mode 100644 index 0000000..7a0d904 --- /dev/null +++ b/packages/core/test/docs-links.test.ts @@ -0,0 +1,52 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { checkLinks, slug } from "../../../scripts/check-links.mjs"; + +const repo = fileURLToPath(new URL("../../../", import.meta.url)); + +// Broken links in public docs read as neglect. Every relative link in the repo's Markdown must resolve. +test("every relative link and anchor in the repo's Markdown resolves", () => { + const r = checkLinks(repo); + assert.ok(r.files > 0 && r.links > 0, "the checker found Markdown files and links"); + assert.deepEqual(r.broken, [], r.broken.map((b: { file: string; line: number; target: string; reason: string }) => `${b.file}:${b.line} ${b.target} (${b.reason})`).join("\n")); +}); + +test("link checker reports a missing file and a missing anchor, and skips code and external links", () => { + const scratch = process.env.TMPDIR; + assert.ok(scratch, "scratch directory required"); + const root = mkdtempSync(join(scratch, "mozak-links-")); + try { + mkdirSync(join(root, "docs")); + writeFileSync(join(root, "docs", "a.md"), "# Title\n\n## Reads and the network\n\n## Reads and the network\n"); + writeFileSync(join(root, "README.md"), [ + "[ok](docs/a.md#reads-and-the-network) [dup](docs/a.md#reads-and-the-network-1) [self](#top)", + "[gone](docs/missing.md) [bad anchor](docs/a.md#nope) [web](https://example.com/x.md)", + "`[in code](docs/missing-in-code.md)`", + "```", + "[in fence](docs/missing-in-fence.md)", + "```", + "", + ].join("\n")); + const r = checkLinks(root); + assert.deepEqual(r.broken.map((b: { target: string; reason: string }) => `${b.target} ${b.reason}`).sort(), ["docs/a.md#nope anchor not found", "docs/missing.md file not found"]); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("heading slugs follow GitHub rules", () => { + assert.equal(slug("Disclosures (Obsidian community plugin policy)"), "disclosures-obsidian-community-plugin-policy"); + assert.equal(slug("Parallel writes: `concurrency.rebase` (experimental, off by default)"), "parallel-writes-concurrencyrebase-experimental-off-by-default"); + assert.equal(slug("6. First implementation contract: portable local installation (3A)"), "6-first-implementation-contract-portable-local-installation-3a"); +}); + +// The npm bundle is now present. Guard the real package name and the source-install alternative. +test("README documents the bundled npm package and source install", () => { + const readme = readFileSync(join(repo, "README.md"), "utf8").replace(//g, ""); + assert.match(readme, /npm install -g mozak/); + assert.match(readme, /node scripts\/install\.mjs/); + assert.doesNotMatch(readme, /npm install -g @mozak\/cli/); +}); diff --git a/packages/core/test/error-messages.test.ts b/packages/core/test/error-messages.test.ts new file mode 100644 index 0000000..ad5e03d --- /dev/null +++ b/packages/core/test/error-messages.test.ts @@ -0,0 +1,117 @@ +// Error messages that name the next step. Codes are unchanged; these tests pin the added guidance. +// Synthetic scopes in temp dirs only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { appendFileSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { executeOperation } from "../src/api.ts"; +import { DomainError } from "../src/errors.ts"; +import { loadInventory, resolveScope } from "../src/scope-index.ts"; +import { initScopeState, mutateScope, readScope } from "../src/scope-store.ts"; + +const scratch = process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR; +if (!scratch) throw new Error("tests require JCODE_SCRATCH_DIR or TMPDIR"); +const roots: string[] = []; +after(() => { for (const root of roots) rmSync(root, { recursive: true, force: true }); }); + +const OWNER_AT = "2026-10-12T08:00:00.000Z"; +const content = (title: string) => ({ + title, purpose: `Purpose for ${title}`, + outcomes: [{ id: "o1", statement: `Statement of ${title}`, acceptance: "objective", criterion: "Check passes" }], + constraints: [], nonGoals: [], rationale: "Synthetic fixture", questions: [], sources: [], +}); + +/** One inventory with the given scope ids, each initialized in its own folder. */ +function world(ids = ["alpha"]) { + const base = mkdtempSync(join(scratch!, "mozak-errmsg-")); + roots.push(base); + const scopes = ids.map((id) => { + const root = join(base, id); + mkdirSync(root); + writeFileSync(join(root, "README.md"), "Human instructions\n"); + writeFileSync(join(root, "AGENTS.md"), "Agent instructions\n"); + return { id, root }; + }); + const config = join(base, "inventory.json"); + writeFileSync(config, JSON.stringify({ format: "mozak.local/v3", scopes })); + for (const s of scopes) initScopeState(s, { operationId: `init-${s.id}`, scopeId: s.id, kind: "project", title: s.id, expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic-owner:init", ownerMessageAt: OWNER_AT }); + return { base, config, scopes, entry: scopes[0]! }; +} +let n = 0; +const propose = (entry: { id: string; root: string }, planId: string, operationId = `op-${++n}`, expected = readScope(entry).snapshot) => + mutateScope(entry, { operationId, scopeId: entry.id, expected, action: "propose", payload: { planId, content: content(planId) } }, "agent"); +const message = (fn: () => unknown, code: string): string => { + try { fn(); } catch (e) { assert.ok(e instanceof DomainError, String(e)); assert.equal(e.code, code); return e.message; } + assert.fail(`expected ${code}`); +}; +const issue = (out: { data: unknown }) => (out.data as { issues: { code: string; message: string }[] }).issues[0]!; + +test("scope-not-found says how to list scope ids", () => { + const w = world(); + const inv = loadInventory(w.config); + assert.match(message(() => resolveScope(inv, "nope"), "scope-not-found"), /^no scope "nope" in the inventory; run mozak scopes \(MCP mozak_scopes\) to list the scope ids$/); + const sync = issue(executeOperation(inv, "sync", { scope: "nope" })); + assert.equal(sync.code, "scope-not-found"); + assert.match(sync.message, /run mozak scopes/); +}); + +test("plan-not-found says how to list plan ids, for context and plans", () => { + const w = world(); + const inv = loadInventory(w.config); + const ctx = issue(executeOperation(inv, "context", { scope: "alpha", plan: "ghost" })); + assert.equal(ctx.code, "plan-not-found"); + assert.match(ctx.message, /^no plan "ghost" in scope "alpha"; run mozak plans \(MCP mozak_plans\) to list the plan ids$/); +}); + +test("stale-input and operation-conflict say to reread and use a new operationId", () => { + const w = world(); + const old = readScope(w.entry).snapshot; + propose(w.entry, "p1", "same-op"); + assert.match(message(() => propose(w.entry, "p2", `op-${++n}`, old), "stale-input"), /take the new snapshot from context as expected and use a new operationId/); + assert.match(message(() => propose(w.entry, "p3", "same-op"), "operation-conflict"), /use a new operationId for a changed request, or read the committed result with mozak operation --id$/); +}); + +test("invalid-json, scope-mismatch and scope-uninitialized name the fix", () => { + const w = world(["alpha", "beta", "gamma"]); + const [alpha, beta, gamma] = w.scopes; + writeFileSync(join(alpha!.root, "mozak.json"), "{ not json"); + assert.match(message(() => readScope(alpha!), "invalid-json"), /restore it from git or fix the syntax by hand, then run mozak check$/); + writeFileSync(join(beta!.root, "mozak.json"), readFileSync(join(gamma!.root, "mozak.json"))); + assert.equal(message(() => readScope(beta!), "scope-mismatch"), 'inventory id "beta" does not match scope.id "gamma" in mozak.json; fix the inventory entry or its root'); + rmSync(join(gamma!.root, "mozak.json")); + assert.match(message(() => readScope(gamma!), "scope-uninitialized"), /^no mozak.json for gamma; check its root in the inventory, or ask the owner to run mozak scope init$/); +}); + +test("busy says another writer is active and to retry", () => { + const w = world(); + const graph = join(w.entry.root, "mozak.json"); + const msg = message(() => readScope(w.entry, { onPhase: () => appendFileSync(graph, " ") }), "busy"); + assert.match(msg, /another writer is active, retry in a few seconds$/); +}); + +test("bridge-unavailable on a write points to check and projection repair", () => { + const w = world(); + const before = readScope(w.entry).snapshot; + writeFileSync(join(w.entry.root, "mozak.md"), "x".repeat(9 * 1024 * 1024)); + assert.match(message(() => propose(w.entry, "p1", `op-${++n}`, before), "bridge-unavailable"), /run mozak check to see why, and ask the owner to run mozak projection repair$/); +}); + +test("an oversized request says to split it", () => { + const w = world(); + const huge = { ...content("big"), rationale: "x".repeat(1024 * 1024 + 1) }; + const msg = message(() => mutateScope(w.entry, { operationId: "big", scopeId: "alpha", expected: readScope(w.entry).snapshot, action: "propose", payload: { planId: "big", content: huge } }, "agent"), "capacity-exceeded"); + assert.equal(msg, "request exceeds 1 MiB; split it into smaller operations"); +}); + +test("continuation-stale says to request the first page again", () => { + const w = world(["alpha", "beta"]); + for (const id of ["p1", "p2", "p3"]) propose(w.entry, id); + const inv = loadInventory(w.config); + const page = executeOperation(inv, "plans", { all: true, limit: 1 }).data as { groups: Record }; + const token = Object.values(page.groups).find((g) => g.continuation)?.continuation; + assert.ok(token, "a full first page yields a continuation"); + propose(w.entry, "p4"); + const changed = issue(executeOperation(inv, "plans", { continuation: token })); + assert.equal(changed.code, "continuation-stale"); + assert.match(changed.message, /since this continuation was issued; request the first page again without a continuation$/); +}); diff --git a/packages/core/test/focus.test.ts b/packages/core/test/focus.test.ts new file mode 100644 index 0000000..869f1a3 --- /dev/null +++ b/packages/core/test/focus.test.ts @@ -0,0 +1,137 @@ +// Focus list: plan ids the owner starred, stored per scope entry in mozak-inventory.json. Synthetic temp folders only. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { executeOperation } from "../src/api.ts"; +import { loadInventory } from "../src/scope-index.ts"; +import { focusChange, focusList, jsonStyle, readFocus, renderFocus, setFocus } from "../src/focus.ts"; + +after(cleanup); +type Issue = { code: string; message: string }; + +/** A two-scope world whose inventory file has a style of its own: one-space indent, x keys, a remote entry, no final newline. */ +function styled() { + const w = world(["alpha", "beta"]); + w.propose("alpha", "a1"); w.propose("alpha", "a2"); w.propose("beta", "b1"); + const text = '{\n "format": "mozak.local/v3",\n "x": { "note": "kept" },\n "scopes": [\n {\n "id": "beta",\n "root": "beta",\n "x": { "colour": "blue" }\n },\n {\n "id": "alpha",\n "root": "alpha"\n },\n {\n "id": "web",\n "remote": "github:owner/web",\n "ref": "main"\n }\n ]\n}'; + writeFileSync(w.config, text); + return { w, text }; +} +const raw = (path: string) => JSON.parse(readFileSync(path, "utf8")); + +test("readFocus: no focus key is an empty list for every scope, including remote entries", () => { + const { w } = styled(); + assert.deepEqual(readFocus(w.config), { alpha: [], beta: [], web: [] }); +}); + +test("setFocus add keeps entry order, indent, final newline style and every other key, and the digest", () => { + const { w, text } = styled(); + const digest = loadInventory(w.config).digest; + const out = setFocus(w.config, { scope: "alpha", plan: "a2", action: "add" }); + assert.deepEqual(out, { scope: "alpha", focus: ["a2"], changed: true }); + const after1 = readFileSync(w.config, "utf8"); + assert.equal(after1.endsWith("}"), true, "no final newline added"); + assert.match(after1, /^\{\n "format"/, "one-space indent kept"); + const obj = raw(w.config); + assert.deepEqual(obj.x, { note: "kept" }); + assert.deepEqual(obj.scopes.map((s: { id: string }) => s.id), ["beta", "alpha", "web"]); + assert.deepEqual(obj.scopes[0].x, { colour: "blue" }); + assert.deepEqual(obj.scopes[1].focus, ["a2"]); + assert.equal(loadInventory(w.config).digest, digest, "focus never changes the inventory digest"); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }); + assert.deepEqual(readFocus(w.config).alpha, ["a2", "a1"]); + setFocus(w.config, { scope: "alpha", plan: "a2", action: "remove" }); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "remove" }); + assert.deepEqual(raw(w.config).scopes[1].focus, [], "an emptied list stays as []"); + assert.notEqual(readFileSync(w.config, "utf8"), text); +}); + +test("setFocus is idempotent: adding twice or removing an absent id changes nothing on disk", () => { + const { w } = styled(); + setFocus(w.config, { scope: "beta", plan: "b1", action: "add" }); + const once = readFileSync(w.config, "utf8"); + assert.deepEqual(setFocus(w.config, { scope: "beta", plan: "b1", action: "add" }), { scope: "beta", focus: ["b1"], changed: false }); + assert.equal(readFileSync(w.config, "utf8"), once); + assert.deepEqual(setFocus(w.config, { scope: "alpha", plan: "a1", action: "remove" }), { scope: "alpha", focus: [], changed: false }); + assert.equal(readFileSync(w.config, "utf8"), once); +}); + +test("setFocus add refuses an unknown scope or plan and leaves the file byte-identical", () => { + const { w, text } = styled(); + assert.throws(() => setFocus(w.config, { scope: "gamma", plan: "a1", action: "add" }), { code: "scope-not-found" }); + assert.throws(() => setFocus(w.config, { scope: "alpha", plan: "b1", action: "add" }), { code: "plan-not-found" }); + assert.throws(() => setFocus(w.config, { scope: "alpha", plan: "a1", action: "toggle" as "add" }), { code: "invalid-input" }); + assert.equal(readFileSync(w.config, "utf8"), text); +}); + +test("setFocus remove works for a plan that no longer exists, so a stale star can be cleared", () => { + const { w } = styled(); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }); + const obj = raw(w.config); + obj.scopes[1].focus.push("gone"); + writeFileSync(w.config, JSON.stringify(obj, null, 1)); + assert.deepEqual(setFocus(w.config, { scope: "alpha", plan: "gone", action: "remove" }).focus, ["a1"]); +}); + +test("the inventory loader accepts focus on local and remote entries and refuses a bad one", () => { + const { w } = styled(); + const put = (focus: unknown, index = 1) => { const o = raw(w.config); o.scopes[index].focus = focus; writeFileSync(w.config, JSON.stringify(o, null, 1)); }; + put(["a1"]); assert.doesNotThrow(() => loadInventory(w.config)); + put(["x"], 2); assert.doesNotThrow(() => loadInventory(w.config)); + for (const bad of ["a1", [1], ["a1", "a1"], [""], {}]) { + put(bad); + assert.throws(() => loadInventory(w.config), { code: "inventory-invalid" }, JSON.stringify(bad)); + } +}); + +test("a failed write leaves the old file valid and no temp file behind", () => { + const { w, text } = styled(); + // A busy inventory lock: the write waits briefly, then refuses with busy and writes nothing. + mkdirSync(join(w.base, ".mozak-inventory-lock")); + writeFileSync(join(w.base, ".mozak-inventory-lock", "owner.json"), JSON.stringify({ token: "t", pid: 1 })); + assert.throws(() => setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }, { lockTimeoutMs: 20 }), { code: "busy" }); + assert.equal(readFileSync(w.config, "utf8"), text); + assert.deepEqual(readdirSync(w.base).filter((n) => n.endsWith(".tmp")), []); +}); + +test("check warns focus-unknown-plan for a starred id that no longer exists, never an error", () => { + const w = world(["alpha"]); + w.propose("alpha", "a1"); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }); + const obj = raw(w.config); obj.scopes[0].focus.push("gone"); writeFileSync(w.config, JSON.stringify(obj, null, 1)); + const check = executeOperation(loadInventory(w.config), "check", { scope: "alpha" }); + assert.equal(check.exitCode, 0, JSON.stringify(check.data)); + assert.equal(check.data.status, "ok"); + const issues = check.data.issues as Issue[]; + assert.deepEqual(issues.filter((i) => i.code === "focus-unknown-plan").map((i) => i.message.includes("gone")), [true]); +}); + +test("focus is never written to mozak.json or mozak.md", () => { + const { w } = styled(); + const before = w.bytes("alpha"); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }); + assert.deepEqual(w.bytes("alpha"), before); +}); + +test("focusList and focusChange return envelopes; renderFocus prints one line per scope", () => { + const { w } = styled(); + assert.deepEqual(focusChange(w.config, { scope: "alpha", plan: "a1", action: "add" }), { exitCode: 0, data: { status: "ok", scope: "alpha", focus: ["a1"], changed: true } }); + const bad = focusChange(w.config, { scope: "alpha", plan: "nope", action: "add" }); + assert.equal(bad.exitCode, 2); + assert.equal(bad.data.status, "plan-not-found"); + assert.deepEqual(focusList(loadInventory(w.config), {}).data.focus, { alpha: ["a1"], beta: [], web: [] }); + assert.deepEqual(focusList(loadInventory(w.config), { scope: "alpha" }), { exitCode: 0, data: { status: "ok", focus: { alpha: ["a1"] } } }); + const missing = focusList(loadInventory(w.config), { scope: "gamma" }); + assert.equal(missing.exitCode, 2); + assert.equal(missing.data.status, "scope-not-found"); + const inv = loadInventory(w.config); + assert.deepEqual(focusList({ format: inv.format, scopes: inv.scopes, digest: inv.digest }, {}).data.focus, { alpha: [], beta: [], web: [] }, "an inventory without a file has empty lists"); + assert.equal(renderFocus({ alpha: ["a1", "a2"], beta: [] }), "alpha: a1, a2\nbeta: (none)\n"); +}); + +test("jsonStyle keeps tab indents and the default when the file has none", () => { + assert.deepEqual(jsonStyle('{\n\t"a": 1\n}\n'), { indent: "\t", newline: true }); + assert.deepEqual(jsonStyle('{"a":1}'), { indent: " ", newline: false }); +}); diff --git a/packages/core/test/graph.test.ts b/packages/core/test/graph.test.ts deleted file mode 100644 index 10f7fcb..0000000 --- a/packages/core/test/graph.test.ts +++ /dev/null @@ -1,65 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { buildGraph, renderMermaid, renderText, targetKey } from "../src/index.ts"; - -function scope(root: string, rel: string, id: string, kind: "project" | "topic", links: string[]) { - const dir = join(root, rel); - mkdirSync(dir, { recursive: true }); - writeFileSync(join(dir, "README.md"), `# ${id}\n`); - writeFileSync(join(dir, "AGENTS.md"), `# ${id}\n`); - writeFileSync(join(dir, "mozak.md"), `---\nid: ${id}\nkind: ${kind}\nformat: 1\n---\n## Plan\n## Links\n${links.join("\n")}\n## Translations\n`); - return dir; -} - -test("targetKey reads wikilinks and repo urls", () => { - assert.equal(targetKey("[[personal-research]]"), "personal-research"); - assert.equal(targetKey("[[note|alias]]"), "note"); - assert.equal(targetKey("https://github.com/pitfa19/mozak.git"), "mozak"); - assert.equal(targetKey("https://github.com/pitfa19/mozak/"), "mozak"); -}); - -test("graph spans a vault and a folder of repos", () => { - const root = mkdtempSync(join(tmpdir(), "mozak-g-")); - scope(root, "vault/topics/research", "research", "topic", ["- informs: https://github.com/me/app", "- derived-from: [[missing-topic]]"]); - scope(root, "repos/app", "app", "project", ["- depends-on: [[research]]"]); - const g = buildGraph({ roots: [join(root, "vault"), join(root, "repos")] }); - assert.deepEqual(g.nodes.map((n) => n.id), ["app", "research"]); - assert.equal(g.nodes.every((n) => n.ok), true); - const informs = g.edges.find((e) => e.relation === "informs"); - assert.equal(informs?.to, "app"); - assert.equal(g.edges.find((e) => e.relation === "depends-on")?.to, "research"); - assert.equal(g.edges.find((e) => e.target === "[[missing-topic]]")?.to, null); - assert.match(renderText(g), /derived-from -> \[\[missing-topic\]\] \[unresolved here\]/); - assert.match(renderMermaid(g), /research -->\|informs\| app/); -}); - -test("explicit map resolves a link whose name does not match the id", () => { - const root = mkdtempSync(join(tmpdir(), "mozak-g-")); - const dir = scope(root, "repos/x", "renamed", "project", []); - scope(root, "vault/a", "a", "topic", ["- informs: https://github.com/me/old-name"]); - const g = buildGraph({ roots: [root], map: { "https://github.com/me/old-name": dir } }); - assert.equal(g.edges[0].to, "renamed"); -}); - -test("duplicate ids are reported, not silently merged", () => { - const root = mkdtempSync(join(tmpdir(), "mozak-g-")); - scope(root, "one", "same", "project", []); - scope(root, "two", "same", "project", []); - const g = buildGraph({ roots: [root] }); - assert.equal(g.nodes.length, 1); - assert.match(g.problems[0], /duplicate scope id "same"/); -}); - -test("a scope that fails check still appears and is flagged", () => { - const root = mkdtempSync(join(tmpdir(), "mozak-g-")); - const dir = scope(root, "bad", "bad", "project", []); - writeFileSync(join(dir, "AGENTS.md"), ""); - // remove a required file by overwriting MOZAK links with an invalid relation instead - writeFileSync(join(dir, "mozak.md"), `---\nid: bad\nkind: project\nformat: 1\n---\n## Plan\n## Links\n- likes: x\n## Translations\n`); - const g = buildGraph({ roots: [root] }); - assert.equal(g.nodes[0].ok, false); - assert.match(renderText(g), /\[check failed\]/); -}); diff --git a/packages/core/test/init.test.ts b/packages/core/test/init.test.ts deleted file mode 100644 index 3aa4eb7..0000000 --- a/packages/core/test/init.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { mkdirSync, mkdtempSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { checkScope } from "../src/check.ts"; -import { auditProject, initScope } from "../src/init.ts"; - -const tmp = () => mkdtempSync(join(tmpdir(), "mozak-i-")); - -/** Every file path with its content, so a before/after comparison catches any write. */ -function snapshot(root: string): Record { - const out: Record = {}; - const walk = (p: string) => { - for (const e of readdirSync(p, { withFileTypes: true })) { - const q = join(p, e.name); - if (e.isDirectory()) walk(q); - else out[q] = readFileSync(q, "utf8"); - } - }; - walk(root); - return out; -} - -test("retired format-1 init refuses before creating a directory", () => { - const parent = tmp(); - const dir = join(parent, "My Project"); - assert.throws(() => initScope(dir, { kind: "project" }), { code: "unsupported-legacy-operation" }); - assert.deepEqual(readdirSync(parent), []); -}); - -test("retired format-1 init preserves existing entry documents", () => { - const dir = tmp(); - writeFileSync(join(dir, "README.md"), "mine\n"); - const before = snapshot(dir); - assert.throws(() => initScope(dir, { kind: "topic", id: "t" }), { code: "unsupported-legacy-operation" }); - assert.deepEqual(snapshot(dir), before); -}); - -test("audit reads old state, proposes a valid draft, and changes no file", () => { - const dir = tmp(); - mkdirSync(join(dir, ".mozak", "features"), { recursive: true }); - mkdirSync(join(dir, ".mozak", "evidence"), { recursive: true }); - writeFileSync(join(dir, ".mozak", "project.yml"), "version: 1\nproject:\n id: oldie\n name: Oldie\n"); - writeFileSync(join(dir, ".mozak", "idea.md"), "# idea\n\n## Intent\n\nShip the thing.\n\n## Open questions\n\n- Which host?\n- Pricing?\n"); - writeFileSync(join(dir, ".mozak", "features", "a.json"), "{}"); - - const before = snapshot(dir); - const a = auditProject(dir); - assert.deepEqual(snapshot(dir), before, "audit must not add, remove or change any file"); - - assert.equal(a.hasOldState, true); - assert.equal(a.oldId, "oldie"); - assert.equal(a.intent, "Ship the thing."); - assert.deepEqual(a.openQuestions, ["Which host?", "Pricing?"]); - assert.equal(a.counts.features, 1); - assert.match(a.draft, /id: oldie/); - assert.match(a.draft, /- \[ \] Pricing\?/); - assert.ok(a.notes.some((n) => /1 feature files/.test(n))); - - // the proposed draft must itself be a valid mozak.md - writeFileSync(join(dir, "README.md"), "x\n"); - writeFileSync(join(dir, "AGENTS.md"), "x\n"); - writeFileSync(join(dir, "mozak.md"), a.draft); - assert.equal(checkScope(dir).ok, true); -}); - -test("audit of a directory with no old state says so", () => { - const a = auditProject(tmp()); - assert.equal(a.hasOldState, false); - assert.match(a.notes[0], /nothing to port/); -}); - -test("audit survives a dangling symlink inside old evidence", () => { - const dir = tmp(); - mkdirSync(join(dir, ".mozak", "evidence", "run", "profile"), { recursive: true }); - writeFileSync(join(dir, ".mozak", "evidence", "run", "real.json"), "{}"); - symlinkSync("/nonexistent/target", join(dir, ".mozak", "evidence", "run", "profile", "SingletonCookie")); - const a = auditProject(dir); - assert.equal(a.counts.evidence, 2); -}); diff --git a/packages/core/test/notes.test.ts b/packages/core/test/notes.test.ts new file mode 100644 index 0000000..34a01ba --- /dev/null +++ b/packages/core/test/notes.test.ts @@ -0,0 +1,63 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { touched } from "../src/notes.ts"; + +// touched() derives change times from git. These tests moved here from the deleted format-1 stale report tests. + +const D = (iso: string) => Math.floor(Date.parse(iso + "T12:00:00Z") / 1000); + +function repo(): string { + const dir = mkdtempSync(join(tmpdir(), "mozak-notes-")); + execFileSync("git", ["init", "-q", "-b", "main", dir]); + execFileSync("git", ["-C", dir, "config", "user.email", "t@t"]); + execFileSync("git", ["-C", dir, "config", "user.name", "t"]); + return dir; +} + +/** Write files then commit them with a fixed date, so assertions can be exact. */ +function commit(dir: string, files: Record, date: string) { + for (const [rel, text] of Object.entries(files)) { + const p = join(dir, rel); + mkdirSync(join(p, ".."), { recursive: true }); + writeFileSync(p, text); + } + const when = `${date}T12:00:00Z`; + execFileSync("git", ["-C", dir, "add", "-A"]); + execFileSync("git", ["-C", dir, "commit", "-q", "-m", "c", "--date", when], { env: { ...process.env, GIT_COMMITTER_DATE: when } }); +} + +test("touched reads the commit date of a file and of a directory", () => { + const r = repo(); + commit(r, { "a/one.md": "1\n", "b/two.md": "2\n" }, "2026-01-10"); + commit(r, { "a/one.md": "1b\n" }, "2026-03-05"); + assert.deepEqual(touched(join(r, "a")), { epoch: D("2026-03-05"), source: "commit" }); + assert.deepEqual(touched(join(r, "b/two.md")), { epoch: D("2026-01-10"), source: "commit" }); +}); + +test("uncommitted edits count as newer than the last commit", () => { + const r = repo(); + commit(r, { "a/one.md": "1\n" }, "2026-01-10"); + writeFileSync(join(r, "a/one.md"), "edited\n"); + const t = touched(join(r, "a")); + assert.equal(t.source, "uncommitted"); + assert.ok(t.epoch! > D("2026-01-10")); +}); + +test("a file with no git history is unknown, not fresh", () => { + const dir = mkdtempSync(join(tmpdir(), "mozak-nogit-")); + writeFileSync(join(dir, "x.md"), "x\n"); + assert.deepEqual(touched(join(dir, "x.md")), { epoch: null, source: "none" }); +}); + +test("an untracked file in a dirty tree does not crash and uses its mtime", () => { + const r = repo(); + commit(r, { "api/README.md": "# api\n" }, "2026-01-10"); + writeFileSync(join(r, "api/new.md"), "fresh\n"); + const old = new Date("2026-02-01T00:00:00Z"); + utimesSync(join(r, "api/new.md"), old, old); + assert.equal(touched(join(r, "api")).source, "uncommitted"); +}); diff --git a/packages/core/test/parse.test.ts b/packages/core/test/parse.test.ts deleted file mode 100644 index 3ae0623..0000000 --- a/packages/core/test/parse.test.ts +++ /dev/null @@ -1,180 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { mkdtempSync, symlinkSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { parseMozak, checkScope } from "../src/index.ts"; - -const good = `--- -id: demo -kind: project -format: 1 ---- - -## Plan - -- [ ] ship it - -## Links - -- depends-on: https://github.com/pitfa19/mozak -- informs: [[personal-research]] - -## Translations - -### publishing concept -- source: [[personal-research]] -- target: https://github.com/pitfa19/anpit-web -- [re-derived] deploys from main -- [re-derived] markdown build step -`; - -test("parses a valid mozak.md", () => { - const d = parseMozak(good); - assert.deepEqual(d.issues, []); - assert.equal(d.id, "demo"); - assert.equal(d.links.length, 2); - assert.equal(d.translations[0].assumptions.length, 2); -}); - -test("rejects missing frontmatter", () => { - assert.equal(parseMozak("## Plan\n").issues[0].code, "frontmatter-missing"); -}); - -test("rejects unknown relation and bad target", () => { - const d = parseMozak(good.replace("depends-on: https://github.com/pitfa19/mozak", "likes: foo")); - assert.ok(d.issues.some((i) => i.code === "link-relation")); - const d2 = parseMozak(good.replace("[[personal-research]]\n\n##", "not-a-link\n\n##")); - assert.ok(d2.issues.some((i) => i.code === "link-target")); -}); - -test("an open assumption makes a translation invalid", () => { - const d = parseMozak(good.replace("[re-derived] markdown build step", "[open] markdown build step")); - const issue = d.issues.find((i) => i.code === "translation-open-assumption"); - assert.ok(issue); - assert.match(issue.message, /markdown build step/); -}); - -test("a translation with no assumptions is invalid", () => { - const d = parseMozak(good.replace(/- \[re-derived\].*\n/g, "")); - assert.ok(d.issues.some((i) => i.code === "translation-no-assumptions")); -}); - -test("sections must be present and ordered", () => { - const d = parseMozak("---\nid: x\nkind: topic\nformat: 1\n---\n## Links\n## Plan\n"); - assert.ok(d.issues.some((i) => i.code === "section-order")); - assert.ok(d.issues.some((i) => i.code === "section-missing")); -}); - -test("checkScope needs the three root files", () => { - const dir = mkdtempSync(join(tmpdir(), "mozak-")); - writeFileSync(join(dir, "mozak.md"), good); - const r = checkScope(dir); - assert.equal(r.ok, false); - assert.deepEqual(r.issues.map((i) => i.message).sort(), ["missing AGENTS.md", "missing README.md"]); - writeFileSync(join(dir, "README.md"), "# demo\n"); - writeFileSync(join(dir, "AGENTS.md"), "# agents\n"); - assert.equal(checkScope(dir).ok, true); -}); - -function claudeIssues(setup: (dir: string) => void): number { - const dir = mkdtempSync(join(tmpdir(), "mozak-")); - for (const f of ["README.md", "AGENTS.md"]) writeFileSync(join(dir, f), "x\n"); - writeFileSync(join(dir, "mozak.md"), good); - setup(dir); - return checkScope(dir).issues.filter((i) => i.code === "claude-pointer").length; -} - -test("no CLAUDE.md is fine, Claude Code 2.1.277+ falls back to AGENTS.md", () => { - assert.equal(claudeIssues(() => {}), 0); -}); - -test("a CLAUDE.md that only says in words to read AGENTS.md is flagged, it is not an import", () => { - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "See AGENTS.md\n")), 1); - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "Read AGENTS.md first.\n")), 1); - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "lots of separate instructions\n")), 1); -}); - -test("a CLAUDE.md with an @AGENTS.md import passes, with or without extra Claude instructions", () => { - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "@AGENTS.md\n")), 0); - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "@AGENTS.md\n\n## Claude Code\n\nUse plan mode.\n")), 0); -}); - -test("@AGENTS.md inside a code span or fenced block is not an import and is flagged", () => { - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "Mentions `@AGENTS.md` only\n")), 1); - assert.equal(claudeIssues((d) => writeFileSync(join(d, "CLAUDE.md"), "```\n@AGENTS.md\n```\n")), 1); -}); - -test("a CLAUDE.md symlinked to AGENTS.md passes, one symlinked elsewhere or dangling is flagged", () => { - assert.equal(claudeIssues((d) => symlinkSync("AGENTS.md", join(d, "CLAUDE.md"))), 0); - assert.equal( - claudeIssues((d) => { - writeFileSync(join(d, "OTHER.md"), "x\n"); - symlinkSync("OTHER.md", join(d, "CLAUDE.md")); - }), - 1, - ); - assert.equal(claudeIssues((d) => symlinkSync("/nonexistent/target", join(d, "CLAUDE.md"))), 1); -}); - -// Line numbers are 1-based lines of the whole file, frontmatter included, so an editor can jump to them. -test("links, translations and assumptions carry the file line they came from", () => { - const d = parseMozak(good); - assert.deepEqual(d.links.map((l) => [l.relation, l.line]), [["depends-on", 13], ["informs", 14]]); - assert.equal(d.translations[0].line, 18); - assert.equal(d.translations[0].source, "[[personal-research]]"); - assert.equal(d.translations[0].target, "https://github.com/pitfa19/anpit-web"); - assert.deepEqual(d.translations[0].assumptions.map((a) => [a.text, a.line]), [["deploys from main", 21], ["markdown build step", 22]]); - assert.equal(d.plan, "- [ ] ship it"); -}); - -test("issues point at the offending line", () => { - const lineOf = (text: string, code: string) => parseMozak(text).issues.find((i) => i.code === code)?.line; - assert.equal(lineOf(good.replace("- informs: [[personal-research]]", "- just words"), "link-malformed"), 14); - assert.equal(lineOf(good.replace("- informs: [[personal-research]]", "- likes: [[x]]"), "link-relation"), 14); - assert.equal(lineOf(good.replace("- depends-on: https://github.com/pitfa19/mozak", "- depends-on: nowhere"), "link-target"), 13); - assert.equal(lineOf(good.replace("[re-derived] markdown", "[open] markdown"), "translation-open-assumption"), 22); - assert.equal(lineOf(good.replace("- target: https://github.com/pitfa19/anpit-web\n", ""), "translation-incomplete"), 18); - assert.equal(lineOf(good.replace(/- \[re-derived\].*\n/g, ""), "translation-no-assumptions"), 18); - assert.equal(lineOf(`${good}\n## Plan\n`, "section-duplicate"), 24); -}); - -test("line numbers stay right with CRLF endings and a longer frontmatter", () => { - const d = parseMozak(good.replace("format: 1\n", "format: 1\ntitle: Demo # a comment\n").replace(/\n/g, "\r\n")); - assert.deepEqual(d.issues, []); - assert.deepEqual(d.links.map((l) => l.line), [14, 15]); - assert.equal(d.translations[0].assumptions[1].line, 23); -}); - -test("frontmatter: id, kind and format are checked, comments are stripped", () => { - const codes = (text: string) => parseMozak(text).issues.map((i) => i.code); - assert.equal(parseMozak(good.replace("kind: project", "kind: topic # notes")).kind, "topic"); - assert.deepEqual(codes(good.replace("id: demo\n", "")), ["id-missing"]); - assert.deepEqual(codes(good.replace("kind: project", "kind: repo")), ["kind-invalid"]); - assert.deepEqual(codes(good.replace("format: 1", "format: 2")), ["format-unsupported"]); - assert.deepEqual(codes("---\nid: x\n"), ["frontmatter-missing"]); - assert.deepEqual(codes(`x\n${good}`), ["frontmatter-missing"]); -}); - -test("unknown sections are reported, and list markers, blank lines and stray lines are ignored", () => { - const d = parseMozak(good.replace("## Translations", "## Notes\n\nfree text\n\n## Translations").replace("- [ ] ship it", "- [ ] ship it\n- [x] done")); - assert.deepEqual(d.issues.map((i) => i.code), ["section-unknown"]); - assert.equal(d.plan, "- [ ] ship it\n- [x] done"); - const starred = parseMozak(good.replace("- informs:", "* informs:").replace("- source:", "source:")); - assert.deepEqual(starred.issues, []); - assert.equal(starred.links[1].relation, "informs"); - assert.equal(starred.translations[0].source, "[[personal-research]]"); - const beforeHeading = parseMozak(good.replace("### publishing concept", "- [open] orphan\n### publishing concept")); - assert.deepEqual(beforeHeading.issues, []); -}); - -test("messages and titles carry the parsed names, and odd shapes do not crash", () => { - const rel = parseMozak(good.replace("- informs: [[personal-research]]", "- likes: [[x]]")).issues.find((i) => i.code === "link-relation"); - assert.match(rel!.message, /^unknown relation "likes" /); - assert.equal(parseMozak(good).translations[0].title, "publishing concept"); - const empty = parseMozak("---\n---\n## Plan\n## Links\n## Translations\n"); - assert.deepEqual(empty.issues.map((i) => i.code), ["id-missing", "kind-invalid", "format-unsupported"]); - const noPlan = parseMozak("---\nid: x\nkind: topic\nformat: 1\n---\n## Links\n## Translations\n"); - assert.equal(noPlan.plan, ""); - assert.deepEqual(noPlan.issues.map((i) => i.code), ["section-missing"]); -}); diff --git a/packages/core/test/paths.test.ts b/packages/core/test/paths.test.ts new file mode 100644 index 0000000..93f28d5 --- /dev/null +++ b/packages/core/test/paths.test.ts @@ -0,0 +1,36 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, symlinkSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { foldKey, foldText } from "../src/fold.ts"; +import { isWithin, realOrSelf } from "../src/paths.ts"; +import { noteKey } from "../src/notes.ts"; + +test("realOrSelf resolves a symlink and returns a missing path unchanged", () => { + const root = realOrSelf(mkdtempSync(join(tmpdir(), "mozak-paths-"))); + mkdirSync(join(root, "real")); + symlinkSync(join(root, "real"), join(root, "link")); + assert.equal(realOrSelf(join(root, "link")), join(root, "real")); + assert.equal(realOrSelf(join(root, "missing", "x")), join(root, "missing", "x")); + assert.equal(realOrSelf("relative/missing"), "relative/missing"); +}); + +test("isWithin accepts the folder itself and children, and refuses siblings, parents and look-alike prefixes", () => { + assert.equal(isWithin("/a/b", "/a/b"), true); + assert.equal(isWithin("/a/b/c/d.md", "/a/b"), true); + assert.equal(isWithin("/a", "/a/b"), false); + assert.equal(isWithin("/a/bc", "/a/b"), false); + assert.equal(isWithin("/x/b", "/a/b"), false); +}); + +test("core folding folds every Croatian letter", () => { + const sample = "čćšžđ ČĆŠŽĐ Đurđevac Šibenik žaba abc ÄÖ"; + assert.equal(foldText(sample), "ccszd CCSZD Durdevac Sibenik zaba abc ÄÖ"); + assert.equal(foldKey("Đurđevac"), "durdevac"); +}); + +test("noteKey folds, lowercases, drops .md and trims", () => { + assert.equal(noteKey(" Šuma Đaka.md"), "suma daka"); + assert.equal(noteKey("Plan.MD"), "plan"); +}); diff --git a/packages/core/test/plan.test.ts b/packages/core/test/plan.test.ts deleted file mode 100644 index 4bfbe1f..0000000 --- a/packages/core/test/plan.test.ts +++ /dev/null @@ -1,28 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { parseMozak } from "../src/parse.ts"; -import { setPlan } from "../src/plan.ts"; - -const doc = `---\nid: x\nkind: project\nformat: 1\n---\n\n## Plan\n\n- [ ] old\n\n## Links\n\n- informs: [[a]]\n\n## Translations\n\n### t\n- source: [[a]]\n- target: [[x]]\n- [open] foo\n`; - -test("setPlan replaces only the plan and leaves Links and Translations byte for byte", () => { - const out = setPlan(doc, "- [ ] new one\n- [x] done"); - const before = doc.slice(doc.indexOf("## Links")); - assert.equal(out.slice(out.indexOf("## Links")), before); - assert.equal(parseMozak(out).plan, "- [ ] new one\n- [x] done"); - assert.equal(parseMozak(out).links.length, 1); -}); - -test("setPlan refuses text that would add a heading", () => { - assert.throws(() => setPlan(doc, "ok\n## Links\n- depends-on: https://evil.example"), /must not contain ## headings/); -}); - -test("setPlan with empty text clears the plan and keeps the structure valid", () => { - const out = setPlan(doc, ""); - assert.equal(parseMozak(out).plan, ""); - assert.equal(parseMozak(out).issues.filter((i) => i.code !== "translation-open-assumption").length, 0); -}); - -test("setPlan on a file without a plan section fails loudly", () => { - assert.throws(() => setPlan("no sections", "x"), /no "## Plan"/); -}); diff --git a/packages/core/test/rebase.test.ts b/packages/core/test/rebase.test.ts new file mode 100644 index 0000000..f8c1fb5 --- /dev/null +++ b/packages/core/test/rebase.test.ts @@ -0,0 +1,348 @@ +// S1b read-set rebase (V-race cases 2 to 7 in process). Synthetic scopes in temp dirs only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { initScopeState, readScope, mutateScope, type StoreOptions } from "../src/scope-store.ts"; +import { applyMutation, outcomeStatus, reviewShow } from "../src/review.ts"; +import { REBASE_GUARD_MS } from "../src/rebase.ts"; +import { canonical, type ScopeState } from "../src/understanding.ts"; + +const scratch = process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR; +if (!scratch) throw new Error("tests require JCODE_SCRATCH_DIR or TMPDIR"); +const roots: string[] = []; +after(() => { for (const root of roots) rmSync(root, { recursive: true, force: true }); }); + +// `rebase` stands for the resolved concurrency.rebase setting (see settings-rebase.test.ts for the file). +type Entry = { id: string; root: string; rebase: boolean }; +const OWNER_AT = "2026-10-12T08:00:00.000Z"; +const INSPECTED = "2026-10-12T08:30:00.000Z"; +// Tests that are not about the guard window turn it off through the internal seam. +const NO_GUARD: StoreOptions = { rebaseGuardMs: 0 }; + +const content = (title = "Understand plans", outcomes = ["o1", "o2", "o3"]) => ({ + title, purpose: `Purpose for ${title}`, + outcomes: outcomes.map(id => ({ id, statement: `Statement ${id} of ${title}`, acceptance: "objective", criterion: `Check ${id} passes` })), + constraints: [], nonGoals: [], rationale: "Synthetic fixture", questions: [], sources: [], +}); + +function world(rebase: boolean | null = true): Entry { + const root = mkdtempSync(join(scratch!, "mozak-rebase-")); + roots.push(root); + writeFileSync(join(root, "README.md"), "Human instructions\n"); + writeFileSync(join(root, "AGENTS.md"), "Agent instructions\n"); + const entry = { id: "sample", root, rebase: rebase === true }; + initScopeState(entry, { operationId: "init-1", scopeId: "sample", kind: "project", title: "Sample", expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic-owner:init", ownerMessageAt: OWNER_AT }); + return entry; +} + +let counter = 0; +const op = () => `op-${++counter}`; +function write(entry: Entry, action: string, payload: unknown, expected = readScope(entry).snapshot, actor: "agent" | "owner" = "agent", options: StoreOptions = NO_GUARD) { + return mutateScope(entry, { operationId: op(), scopeId: entry.id, expected, action, payload }, actor, { rebase: entry.rebase, ...options }); +} +function approve(entry: Entry, planId: string, options: StoreOptions = NO_GUARD) { + const shown = reviewShow(readScope(entry).state, planId, "approve-direction"); + return write(entry, "approve-direction", { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: `synthetic-owner:${op()}`, ownerMessageAt: OWNER_AT, reason: "fixture approval" }, undefined, "owner", options); +} +/** Scope with plan p1 proposed and accepted, three objective outcomes. */ +function accepted(rebase: boolean | null = true): Entry { + const entry = world(rebase); + write(entry, "propose", { planId: "p1", content: content() }); + approve(entry, "p1"); + return entry; +} +const acceptedId = (entry: Entry, planId = "p1") => readScope(entry).state.plans.find(p => p.id === planId)!.accepted!.id; +function observation(id: string, opts: { pass?: boolean; supersedes?: string } = {}) { + return { + id, classification: opts.pass === false ? "unverified" : "observed", summary: `claim ${id}`, + evidence: opts.pass === false ? [] : [{ id: `${id}-e`, locator: "test:fixture", anchor: null, version: null, inspectedAt: INSPECTED, activity: { kind: "run", description: "synthetic run" }, result: { verdict: "pass", summary: "passed" }, limitations: [] }], + ...(opts.supersedes ? { supersedesObservationId: opts.supersedes } : {}), + }; +} +function observe(entry: Entry, id: string, outcomeId: string | null, opts: { relation?: string; pass?: boolean; supersedes?: string; planId?: string } = {}) { + const planId = opts.planId ?? "p1"; + return { + planId, observation: observation(id, opts), + reasoningLinks: outcomeId === null ? [] : [{ id: `${id}-l`, relation: opts.relation ?? "supports", from: { planId, revisionId: null, kind: "observation", id }, to: { planId, revisionId: acceptedId(entry, planId), kind: "outcome", id: outcomeId }, rationale: "fixture link" }], + }; +} +function discussion(entry: Entry, planId: string, summary: string) { + const plan = readScope(entry).state.plans.find(p => p.id === planId)!; + return { planId, acceptedRevisionId: plan.accepted?.id ?? null, pendingRevisionId: plan.pending?.id ?? null, summary, stage: "clarifying", questions: [] }; +} +const files = (entry: Entry) => ["mozak.json", "mozak.md"].map(n => readFileSync(join(entry.root, n), "utf8")); + +test("flag off: a stale observe is refused exactly as before and nothing is written", () => { + for (const rebase of [null, false]) { + const entry = accepted(rebase); + const stale = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "a", "o1")); + const before = files(entry); + assert.throws(() => write(entry, "observe", observe(entry, "b", "o2"), stale), { code: "stale-input", message: "snapshot changed; reread before submitting a new operation: take the new snapshot from context as expected and use a new operationId" }); + assert.deepEqual(files(entry), before); + } +}); + +test("flag on: a stale observe on another outcome rebases and reports from, onto and the fresh snapshot", () => { + const entry = accepted(); + const stale = readScope(entry).snapshot; + const first = write(entry, "observe", observe(entry, "a", "o1")); + assert.equal(first.rebased, undefined); + const second = write(entry, "observe", observe(entry, "b", "o2"), stale); + assert.equal(second.status, "ok"); + assert.deepEqual(second.rebased, { from: stale.revision, onto: first.snapshot!.revision }); + assert.deepEqual(second.snapshot, readScope(entry).snapshot); + const plan = readScope(entry).state.plans[0]; + assert.deepEqual(plan.observations.map(o => o.id), ["a", "b"]); +}); + +test("V-race 2: two supersedes of one observation from one snapshot give 1 commit", () => { + const entry = accepted(); + write(entry, "observe", observe(entry, "old", null, { pass: false })); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "unrelated", "o3")); + const results = ["x", "y"].map(id => { try { return write(entry, "observe", observe(entry, id, null, { supersedes: "old" }), snap).status; } catch (e) { return (e as { code: string }).code; } }); + assert.deepEqual(results, ["ok", "stale-input"]); + const obs = readScope(entry).state.plans[0].observations; + assert.equal(obs.filter(o => o.supersedesObservationId === "old").length, 1); +}); + +test("V-race 3: two discussion saves on one plan give 1 commit, while a save on another plan rebases", () => { + const entry = accepted(); + write(entry, "propose", { planId: "p2", content: content("Other subject", ["q1"]) }); + const snap = readScope(entry).snapshot; + const a = discussion(entry, "p1", "first summary"), b = discussion(entry, "p1", "second summary"), c = discussion(entry, "p2", "other plan"); + assert.equal(write(entry, "save-discussion", a, snap).status, "ok"); + assert.throws(() => write(entry, "save-discussion", b, snap), { code: "stale-input" }); + const other = write(entry, "save-discussion", c, snap); + assert.ok(other.rebased); + const state = readScope(entry).state; + assert.equal(state.plans[0].discussion!.summary, "first summary"); + assert.equal(state.plans[1].discussion!.summary, "other plan"); +}); + +test("V-race 4: a revise plus approval racing an observe refuses the observe", () => { + const entry = accepted(); + const snap = readScope(entry).snapshot; + const payload = observe(entry, "late", "o1"); + write(entry, "revise", { planId: "p1", pendingRevisionId: null, acceptedRevisionId: acceptedId(entry), content: { ...content(), rationale: "Changed rationale" } }); + approve(entry, "p1"); + const before = files(entry); + assert.throws(() => write(entry, "observe", payload, snap), { code: "stale-input", message: /revise|approve-direction/ }); + assert.deepEqual(files(entry), before); + // A revise alone (no approval) also refuses: it does not commute even when the link would still resolve. + const entry2 = accepted(); + const snap2 = readScope(entry2).snapshot; + const payload2 = observe(entry2, "late", "o1"); + write(entry2, "revise", { planId: "p1", pendingRevisionId: null, acceptedRevisionId: acceptedId(entry2), content: { ...content(), rationale: "Changed rationale" } }); + assert.throws(() => write(entry2, "observe", payload2, snap2), { code: "stale-input" }); +}); + +test("V-race 5: an owner accept-outcome racing a challenge refuses the decision", () => { + const entry = world(); + write(entry, "propose", { planId: "p1", content: { ...content(), outcomes: [{ id: "o1", statement: "Owner judged", acceptance: "owner", criterion: "Owner agrees" }] } }); + approve(entry, "p1"); + write(entry, "observe", observe(entry, "pass", "o1")); + const snap = readScope(entry).snapshot; + const shown = reviewShow(readScope(entry).state, "p1", "accept-outcome", "o1"); + const decision = { planId: "p1", revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, outcomeId: "o1", ownerRef: "synthetic-owner:accept", ownerMessageAt: OWNER_AT, reason: "looks done" }; + write(entry, "observe", observe(entry, "challenge", "o1", { relation: "challenges" })); + assert.throws(() => write(entry, "accept-outcome", decision, snap, "owner"), { code: "stale-input", message: /accept-outcome is never rebased/ }); + // With a fresh snapshot the old review digest is still refused, so the decision never binds an unseen challenge. + assert.throws(() => write(entry, "accept-outcome", decision, undefined, "owner"), { code: "stale-reference" }); + const state = readScope(entry).state; + assert.equal(state.plans[0].decisions.filter(d => d.purpose === "accept-outcome").length, 0); + assert.equal(outcomeStatus(state, state.plans[0], "o1"), "evidence"); +}); + +test("V-race 6: a rebased write then a second write with the returned snapshot gives no stale", () => { + const entry = accepted(); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "other", "o2")); + const rebased = write(entry, "observe", observe(entry, "mine-1", "o1"), snap); + assert.ok(rebased.rebased); + const next = write(entry, "observe", observe(entry, "mine-2", "o1"), rebased.snapshot!); + assert.equal(next.status, "ok"); + assert.equal(next.rebased, undefined); +}); + +test("observe read set: a changed outcome status, reused ids, an added link source or an unknown revision refuse", () => { + const entry = accepted(); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "first", "o1")); // o1 goes from todo to done + assert.throws(() => write(entry, "observe", observe(entry, "second", "o1"), snap), { code: "stale-input", message: /changed status/ }); + assert.throws(() => write(entry, "observe", observe(entry, "first", "o2"), snap), { code: "stale-input", message: /was used/ }); + const fromAdded = observe(entry, "third", "o2"); + fromAdded.reasoningLinks[0]!.from.id = "first"; + assert.throws(() => write(entry, "observe", fromAdded, snap), { code: "stale-input", message: /was added/ }); + assert.throws(() => write(entry, "observe", observe(entry, "fourth", "o2"), { ...snap, revision: "not-a-known-revision" }), { code: "stale-input", message: /neither current nor a retained receipt/ }); + // A done outcome that stays done is not a status change. + const snap2 = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "fifth", "o1")); + assert.ok(write(entry, "observe", observe(entry, "sixth", "o1"), snap2).rebased); +}); + +test("propose rebases for a free id, refuses a taken id and keeps the duplicate check on fresh state", () => { + const entry = world(); + const snap = readScope(entry).snapshot; + write(entry, "propose", { planId: "a", content: content("Export quarterly revenue report") }); + assert.ok(write(entry, "propose", { planId: "b", content: content("Quite different topic entirely") }, snap).rebased); + assert.throws(() => write(entry, "propose", { planId: "a", content: content("Zebra crossing paint") }, snap), { code: "stale-input", message: /was taken/ }); + assert.throws(() => write(entry, "propose", { planId: "c", content: content("Export quarterly revenue report") }, snap), { code: "duplicate-plan-candidate" }); +}); + +test("never rebased: complete, revise and attach-spec keep the exact snapshot check", () => { + const entry = accepted(); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "n", null, { pass: false })); + assert.throws(() => write(entry, "complete", { planId: "p1", revisionId: acceptedId(entry) }, snap), { code: "stale-input", message: /complete is never rebased/ }); + assert.throws(() => write(entry, "revise", { planId: "p1", pendingRevisionId: null, acceptedRevisionId: acceptedId(entry), content: content("Changed") }, snap), { code: "stale-input", message: /revise is never rebased/ }); + assert.throws(() => write(entry, "attach-spec", { planId: "p1", acceptedRevisionId: acceptedId(entry), path: "spec.md", bounds: { summary: "fixture", allowedPaths: [], excludedActions: [], outcomeChecks: ["o1", "o2", "o3"].map(outcomeId => ({ outcomeId, criterion: "passes" })), limitations: [] }, discussionDigest: null }, snap), { code: "stale-input", message: /attach-spec is never rebased/ }); +}); + +test("guard window: a decision recorded just before the snapshot's receipt refuses the rebase", () => { + const entry = accepted(); + // The approval is the latest non-rebasable receipt. A snapshot taken after one more write still sits inside the window. + write(entry, "observe", observe(entry, "a", null, { pass: false })); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "b", null, { pass: false })); + assert.throws(() => write(entry, "observe", observe(entry, "c", "o2"), snap, "agent", {}), { code: "stale-input", message: /does not commute/ }); + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, REBASE_GUARD_MS + 50); + write(entry, "observe", observe(entry, "d", null, { pass: false })); + const later = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "d2", null, { pass: false })); + assert.ok(write(entry, "observe", observe(entry, "e", "o2"), later, "agent", {}).rebased); +}); + +// ---------- V-race 7: serial equivalence with a seeded generator (fast-check is not a dependency) ---------- + +function rng(seed: number) { + let s = seed >>> 0; + return () => { s = (s + 0x6d2b79f5) >>> 0; let t = s; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; +} + +/** Independent oracle: is the request's read set the same in the true snapshot state and the fresh state? */ +function oracleSafe(s0: ScopeState, s1: ScopeState, between: string[], action: string, p: any): boolean { + if (!["observe", "save-discussion", "propose"].includes(action)) return false; + if (between.some(a => !["observe", "save-discussion", "propose"].includes(a))) return false; + const plan0 = s0.plans.find(x => x.id === p.planId), plan1 = s1.plans.find(x => x.id === p.planId); + if (action === "propose") return !(plan1 && !plan0); + if (!plan0 || !plan1) return false; + if (action === "save-discussion") return canonical(plan0.discussion) === canonical(plan1.discussion); + const ids0 = new Set(plan0.observations.map(o => o.id)), ids1 = new Set(plan1.observations.map(o => o.id)); + if (ids1.has(p.observation.id) && !ids0.has(p.observation.id)) return false; + const supersedersOf = (s: ScopeState, planId: string, id: string) => canonical(s.plans.find(x => x.id === planId)?.observations.filter(o => o.supersedesObservationId === id).map(o => o.id) ?? []); + if (p.observation.supersedesObservationId && supersedersOf(s0, p.planId, p.observation.supersedesObservationId) !== supersedersOf(s1, p.planId, p.observation.supersedesObservationId)) return false; + for (const l of p.reasoningLinks) { + const fromOld = s0.plans.find(x => x.id === l.from.planId)?.observations.some(o => o.id === l.from.id); + const isSelf = l.from.planId === p.planId && l.from.id === p.observation.id; + if (!isSelf && !fromOld) return false; + if (!isSelf && supersedersOf(s0, l.from.planId, l.from.id) !== supersedersOf(s1, l.from.planId, l.from.id)) return false; + const t0 = s0.plans.find(x => x.id === l.to.planId), t1 = s1.plans.find(x => x.id === l.to.planId); + if (!t0 || !t1 || t0.accepted?.id !== t1.accepted?.id || t0.pending?.id !== t1.pending?.id) return false; + if (outcomeStatus(s0, t0, l.to.id) !== outcomeStatus(s1, t1, l.to.id)) return false; + } + return true; +} +/** The rebased write must change the fresh state exactly as the same write changes the snapshot state. */ +function sameEffect(s0: ScopeState, s1: ScopeState, after: ScopeState, action: string, p: any, now: string): boolean { + let serial: ScopeState; + try { serial = applyMutation(s0, action as any, p, "agent", now).state; } catch { return false; } + const strip = (s: ScopeState, base: ScopeState) => { + const out: unknown[] = []; + for (const plan of s.plans) { + const old = base.plans.find(x => x.id === plan.id); + if (!old) { out.push(["plan", plan.id, plan.pending?.content ?? null]); continue; } + for (const o of plan.observations) if (!old.observations.some(x => x.id === o.id)) out.push(["obs", plan.id, { ...o, recordedAt: null }]); + for (const l of plan.reasoningLinks) if (!old.reasoningLinks.some(x => x.id === l.id)) out.push(["link", plan.id, l]); + if (canonical(plan.discussion) !== canonical(old.discussion)) out.push(["discussion", plan.id, plan.discussion ? { summary: plan.discussion.summary, stage: plan.discussion.stage } : null]); + } + return canonical(out); + }; + return strip(serial, s0) === strip(after, s1); +} + +test("V-race 7: seeded random histories with stale snapshots are serially equivalent (0 unsafe rebases)", () => { + const seeds = Number(process.env.MOZAK_VRACE_SEEDS ?? 3), steps = Number(process.env.MOZAK_VRACE_STEPS ?? 60); + let rebasedCount = 0, unsafe = 0, falseRefusals = 0, total = 0, notEquivalent = 0, refused = 0; + for (let seed = 1; seed <= seeds; seed++) { + const r = rng(seed); + const entry = accepted(); + write(entry, "propose", { planId: "p2", content: content("Second unrelated subject", ["q1", "q2"]) }); + approve(entry, "p2"); + const history: { snap: ReturnType["snapshot"]; state: ScopeState; action: string }[] = []; + const push = (action: string) => { const read = readScope(entry); history.push({ snap: read.snapshot, state: read.state, action }); }; + push("start"); + let n = 0; + for (let i = 0; i < steps; i++) { + const back = Math.min(history.length - 1, Math.floor(r() * 4)); + const at = history[history.length - 1 - back]!; + const s0 = at.state; + const between = history.slice(history.length - back).map(h => h.action); + const pick = r(); + const planId = r() < 0.6 ? "p1" : "p2"; + const plan0 = s0.plans.find(p => p.id === planId)!; + const outcomes = plan0.accepted?.content.outcomes.map(o => o.id) ?? []; + let action: string, payload: any, actor: "agent" | "owner" = "agent"; + if (pick < 0.55 && plan0.accepted) { + action = "observe"; + const id = r() < 0.1 && plan0.observations.length ? plan0.observations[Math.floor(r() * plan0.observations.length)]!.id : `o-${seed}-${++n}`; + const supersedes = r() < 0.25 && plan0.observations.length ? plan0.observations[Math.floor(r() * plan0.observations.length)]!.id : undefined; + const target = outcomes[Math.floor(r() * outcomes.length)]!; + const relation = r() < 0.15 ? "challenges" : "supports"; + payload = { planId, observation: observation(id, { pass: r() < 0.7, supersedes }), reasoningLinks: r() < 0.8 ? [{ id: `${id}-l`, relation, from: { planId, revisionId: null, kind: "observation", id }, to: { planId, revisionId: plan0.accepted.id, kind: "outcome", id: target }, rationale: "random" }] : [] }; + } else if (pick < 0.75) { + action = "save-discussion"; + payload = { planId, acceptedRevisionId: plan0.accepted?.id ?? null, pendingRevisionId: plan0.pending?.id ?? null, summary: `summary ${seed}-${++n}`, stage: "clarifying", questions: [] }; + } else if (pick < 0.9) { + action = "propose"; + const words = ["kiwi", "lantern", "quartz", "harbor", "violet", "meadow", "copper", "glacier", "ember", "saffron"]; + const title = Array.from({ length: 4 }, () => words[Math.floor(r() * words.length)]).join(" ") + ` ${seed}-${++n}`; + payload = { planId: r() < 0.2 && s0.plans.length > 2 ? s0.plans[s0.plans.length - 1]!.id : `np-${seed}-${n}`, content: content(title, ["z1"]) }; + } else if (pick < 0.95 && plan0.accepted) { + action = "revise"; + payload = { planId, pendingRevisionId: plan0.pending?.id ?? null, acceptedRevisionId: plan0.accepted.id, content: content(`Revised ${seed}-${++n}`, outcomes) }; + } else { + const challenged = outcomes.find(o => outcomeStatus(s0, plan0, o) === "evidence"); + if (!challenged) { i--; continue; } + action = "accept-outcome"; actor = "owner"; + const shown = reviewShow(s0, planId, "accept-outcome", challenged); + payload = { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, outcomeId: challenged, ownerRef: `synthetic-owner:${seed}-${++n}`, ownerMessageAt: OWNER_AT, reason: "random acceptance" }; + } + const s1 = readScope(entry).state; + const safe = back === 0 ? null : oracleSafe(s0, s1, between, action, payload); + total++; + let res: ReturnType | undefined, code = ""; + try { res = write(entry, action, payload, at.snap, actor); } catch (e) { code = (e as { code: string }).code; } + if (res) { + push(action); + if (res.rebased) { + rebasedCount++; + if (safe !== true) unsafe++; + const after = readScope(entry).state; + if (!sameEffect(s0, s1, after, action, payload, after.storage.updatedAt)) notEquivalent++; + } + } else if (code === "stale-input") { refused++; if (safe === true) falseRefusals++; } + } + } + console.log(`V-race 7: seeds=${seeds} steps/seed=${steps} writes=${total} rebased=${rebasedCount} unsafe=${unsafe} notEquivalent=${notEquivalent} staleRefused=${refused} conservativeRefusals=${falseRefusals}`); + assert.equal(unsafe, 0); + assert.equal(notEquivalent, 0); + assert.ok(rebasedCount > 0, "the generator exercises the rebase path"); +}); + +test("V-race 8: P0.6 with rebase on: a rebased write still refuses when mozak.json or mozak.md changes before its rename", () => { + for (const name of ["mozak.json", "mozak.md"]) { + const entry = accepted(); + const snap = readScope(entry).snapshot; + write(entry, "observe", observe(entry, "other", "o2")); + const changed = name === "mozak.json" ? `${readFileSync(join(entry.root, name), "utf8")}\n` : "External bridge edit\n"; + const graphBefore = readFileSync(join(entry.root, "mozak.json"), "utf8"); + assert.throws(() => mutateScope(entry, { operationId: op(), scopeId: entry.id, expected: snap, action: "observe", payload: observe(entry, "mine", "o1") }, "agent", { ...NO_GUARD, rebase: true, onPhase(p) { + if (p === "before-graph") writeFileSync(join(entry.root, name), changed); + } }), { code: "graph-changed-during-write" }); + assert.equal(readFileSync(join(entry.root, name), "utf8"), changed); + if (name === "mozak.md") assert.equal(readFileSync(join(entry.root, "mozak.json"), "utf8"), graphBefore); + } +}); diff --git a/packages/core/test/release-scope.test.ts b/packages/core/test/release-scope.test.ts new file mode 100644 index 0000000..2a5bdb5 --- /dev/null +++ b/packages/core/test/release-scope.test.ts @@ -0,0 +1,36 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import * as core from "../src/index.ts"; + +// Owner decisions for 0.5.0: the eval harness and the tend experiment stay on the unmerged Hermes branches, and the +// format-1 modules are deleted. +const repo = new URL("../../../", import.meta.url); +const tracked = (): string[] => + execFileSync("git", ["-C", repo.pathname, "ls-files", "-z"], { encoding: "utf8" }).split("\0").filter(Boolean) + .filter((path) => existsSync(new URL(path, repo))); + +test("0.5.0 ships no eval harness and no tend experiment", () => { + for (const path of ["eval", "packages/core/src/tend.ts", "skills/mozak-tend"]) { + assert.equal(existsSync(new URL(path, repo)), false, `${path} must not ship`); + } + assert.deepEqual(Object.keys(core).filter((name) => /tend/i.test(name)), []); + const scripts = Object.keys(JSON.parse(readFileSync(new URL("package.json", repo), "utf8")).scripts); + assert.deepEqual(scripts.filter((name) => /eval/.test(name)), []); +}); + +test("no tracked file names the eval harness or a ~/.hermes path", () => { + const offenders = tracked() + .filter((path) => !path.endsWith("CHANGELOG.md") && !/\.(png|gif|mp4|webp|jpg|ico)$/.test(path) && path !== "packages/core/test/release-scope.test.ts") + .filter((path) => /eval\/(verify|lib|test|run)|\.hermes\//.test(readFileSync(new URL(path, repo), "utf8"))); + assert.deepEqual(offenders, []); +}); + +test("format 1 is gone from core: no parse, check, graph, stale, translate, init, write or plan module or export", () => { + for (const name of ["parse", "check", "graph", "stale", "translate", "init", "write", "plan"]) { + assert.equal(existsSync(new URL(`packages/core/src/${name}.ts`, repo)), false, `${name}.ts must be removed`); + } + const gone = ["parseMozak", "checkScope", "buildGraph", "loadConfig", "staleReports", "renderStale", "buildPacket", "renderTranslation", "auditProject", "mozakTemplate", "readSnapshot", "hashText", "EMPTY_HASH"]; + assert.deepEqual(gone.filter((name) => name in core), []); +}); diff --git a/packages/core/test/remote.test.ts b/packages/core/test/remote.test.ts index 59cab1b..28d7013 100644 --- a/packages/core/test/remote.test.ts +++ b/packages/core/test/remote.test.ts @@ -59,6 +59,16 @@ test("inventory: remote entry validation stays strict, v2 still accepted", () => }); function realpathOf(p: string) { return execFileSync("realpath", [p], { encoding: "utf8" }).trim(); } +test("check warns about a sidecar file in a repo-mode remote scope even though it is never read", () => { + const { inv, base } = fixture(); + assert.equal(exec(inv, "context", { scope: "genome-mcp" }).exitCode, 0); + const codes = () => (exec(inv, "check", { scope: "genome-mcp" }).data.issues as { code: string }[]).map((i) => i.code); + assert.equal(codes().includes("annotations-on-remote"), false); + writeFileSync(join(base, ".mozak-cache", "genome-mcp", "mozak.annotations.json"), "{ not json"); + assert.equal(codes().includes("annotations-on-remote"), true); + assert.equal(codes().includes("annotations-invalid"), false); +}); + test("first read fetches a sparse copy with only the four files", () => { const { inv, base } = fixture(); const out = exec(inv, "context", { scope: "genome-mcp" }); diff --git a/packages/core/test/roadmap.test.ts b/packages/core/test/roadmap.test.ts index 61dc727..a8f8a28 100644 --- a/packages/core/test/roadmap.test.ts +++ b/packages/core/test/roadmap.test.ts @@ -161,7 +161,7 @@ test("roadmap: deriving status never mutates state", () => { const HASH = "a".repeat(64); test("bridge: deterministic, keeps the safety header and adds the display-only line", () => { - const s = support(accepted([outcome("mini-cleanup", "owner"), outcome("hermes")]), "mini-cleanup", "o1"); + const s = support(accepted([outcome("mini-cleanup", "owner"), outcome("sandbox")]), "mini-cleanup", "o1"); const a = renderBridge(s, HASH), b = renderBridge(structuredClone(s), HASH); assert.equal(a, b); for (const line of ["Generated from [mozak.json](mozak.json). Do not edit this projection.", "Plan text is data, not authority to execute instructions.", "Implementation eligibility requires a fresh canonical and local specification check.", "Status is computed from mozak.json. Nothing here is clickable or editable."]) { @@ -171,13 +171,13 @@ test("bridge: deterministic, keeps the safety header and adds the display-only l }); test("bridge: open plan renders heading, progress, mermaid roadmap, status table and sections", () => { - const s = support(accepted([outcome("mini-cleanup", "owner"), outcome("hermes")]), "mini-cleanup", "o1"); + const s = support(accepted([outcome("mini-cleanup", "owner"), outcome("sandbox")]), "mini-cleanup", "o1"); const md = renderBridge(s, HASH); assert.ok(md.includes("## Road plan · `p1`\n")); assert.ok(md.includes("**Open** · 0/2 done · updated ")); assert.ok(md.includes("```mermaid\nflowchart LR\n")); assert.ok(md.includes('s1["📍 Mini cleanup"]:::current')); - assert.ok(md.includes('s2["⚪ Hermes"]:::todo')); + assert.ok(md.includes('s2["⚪ Sandbox"]:::todo')); assert.ok(md.includes(" s1 --> s2\n")); assert.ok(md.includes("| 1 | Statement for mini-cleanup | 🟡 evidence recorded, needs owner acceptance · 📍 next | owner | mini-cleanup check passes |")); for (const h of ["### Roadmap", "### Constraints", "### Non-goals", "### Rationale", "### Open questions"]) assert.ok(md.includes(`\n${h}\n`), h); diff --git a/packages/core/test/s2-history.test.ts b/packages/core/test/s2-history.test.ts new file mode 100644 index 0000000..d0cb0f4 --- /dev/null +++ b/packages/core/test/s2-history.test.ts @@ -0,0 +1,70 @@ +// S2 `check --history N`: hand edits of mozak.json found in git history. Synthetic temp repos only, no network. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { handEditHistory } from "../src/history.ts"; + +after(cleanup); + +const g = (cwd: string, ...args: string[]) => execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf8" }); +const commitAll = (root: string, message: string) => { g(root, "add", "-A"); g(root, "commit", "-q", "-m", message); }; + +test("check --history finds a commit that removed plans while keeping storage.revision, and one with a foreign revision", () => { + const w = world(["alpha"], { git: true }); + const root = w.entries.alpha.root; + commitAll(root, "init"); + w.propose("alpha", "keep"); + w.propose("alpha", "dropped", {}, false); + w.reject("alpha", "dropped"); + commitAll(root, "agent writes"); + // Hand edit like vault commit bada5de: remove a rejected plan, keep storage.revision. + const path = join(root, "mozak.json"); + const state = JSON.parse(readFileSync(path, "utf8")); + state.plans = state.plans.filter((p: { id: string }) => p.id !== "dropped"); + writeFileSync(path, JSON.stringify(state)); + commitAll(root, "hand prune"); + // Clean history so far apart from that one commit. + let report = handEditHistory(root, 10); + assert.equal(report.available, true); + assert.equal(report.scanned, 3); + assert.deepEqual(report.findings.map((f) => [f.code, f.removedPlans]), [["hand-edit", ["dropped"]]]); + // A hand edit that also invents a revision. + state.storage.revision = "hand-made-revision"; + writeFileSync(path, JSON.stringify(state)); + commitAll(root, "hand revision"); + report = handEditHistory(root, 10); + assert.deepEqual(report.findings.map((f) => f.code), ["hand-edit-revision", "hand-edit"]); + // N limits the walk to the newest commits. + assert.deepEqual(handEditHistory(root, 1).findings.map((f) => f.code), ["hand-edit-revision"]); + assert.equal(handEditHistory(root, 1).scanned, 1); + + const out = w.op("check", { scope: "alpha", history: 10 }); + const codes = (out.data.issues as { code: string }[]).map((i) => i.code); + assert.ok(codes.includes("hand-edit") && codes.includes("hand-edit-revision"), codes.join(",")); + assert.deepEqual(out.data.history, { scanned: 4, available: true, handEdits: 2 }); + assert.equal(out.exitCode, 3); + assert.equal(w.op("check", { scope: "alpha", history: 0 }).data.status, "invalid-input"); + assert.equal(w.op("check", { scope: "alpha", history: "5" }).data.status, "invalid-input"); +}); + +test("check --history on clean mozak history and outside git", () => { + const w = world(["alpha"], { git: true }); + const root = w.entries.alpha.root; + commitAll(root, "init"); + w.propose("alpha", "a"); + commitAll(root, "write"); + w.propose("alpha", "b"); + commitAll(root, "write"); + const report = handEditHistory(root, 50); + assert.equal(report.scanned, 3); + assert.deepEqual(report.findings, []); + assert.equal(w.op("check", { scope: "alpha", history: 50 }).exitCode, 0); + + const plain = world(["beta"]); + const none = plain.op("check", { scope: "beta", history: 5 }); + assert.equal(none.exitCode, 0); + assert.equal((none.data.issues as { code: string }[]).some((i) => i.code === "history-unavailable"), true); +}); diff --git a/packages/core/test/s2-offline.test.ts b/packages/core/test/s2-offline.test.ts new file mode 100644 index 0000000..f23bf66 --- /dev/null +++ b/packages/core/test/s2-offline.test.ts @@ -0,0 +1,88 @@ +// S2 offline reads: local and vault-plans reads never fetch; remote reads keep the 10-minute fetch, mark +// remoteFreshness, and after a failed fetch do not retry the network on every read. Local bare repos only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { executeOperation, initScopeState, loadInventory, readRemoteMeta, writeRemoteMeta } from "../src/index.ts"; + +const scratch = process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(); +const made: string[] = []; +after(() => { for (const d of made) { if (!d.includes("/mozak-s2off-")) throw new Error(d); rmSync(d, { recursive: true, force: true }); } }); +const g = (cwd: string, ...args: string[]) => + execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "protocol.file.allow=always", ...args], { cwd, encoding: "utf8", env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }); +const init = (id: string, root: string) => initScopeState({ id, root }, { operationId: `init-${id}`, scopeId: id, kind: "project", title: id, expectedAbsent: { graph: true, bridge: true }, ownerRef: "host:t", ownerMessageAt: "2026-10-12T08:50:00.000Z" }); + +function fixture() { + const base = mkdtempSync(join(scratch, "mozak-s2off-")); + made.push(base); + const bare = join(base, "origin.git"); + const seed = join(base, "seed"); + g(base, "init", "--bare", "-b", "main", bare); + mkdirSync(seed); + g(seed, "init", "-b", "main"); + writeFileSync(join(seed, "README.md"), "# r\n"); + writeFileSync(join(seed, "AGENTS.md"), "# a\n"); + init("repo", seed); + g(seed, "add", "."); g(seed, "commit", "-m", "seed"); g(seed, "remote", "add", "origin", bare); g(seed, "push", "origin", "main"); + // A local scope and a vault-plans scope whose repo URL does not exist: reads must not need it. + const local = join(base, "local"); + const plans = join(base, "notes", "tool"); + for (const dir of [local, plans]) { mkdirSync(dir, { recursive: true }); writeFileSync(join(dir, "README.md"), "# r\n"); writeFileSync(join(dir, "AGENTS.md"), "# a\n"); } + init("local", local); + const inv = join(base, "inventory.json"); + writeFileSync(inv, JSON.stringify({ format: "mozak.local/v3", scopes: [ + { id: "repo", remote: `file://${bare}`, ref: "main" }, + { id: "local", root: "local" }, + { id: "tool", remote: `file://${join(base, "missing.git")}`, plans: "notes/tool" }, + ] })); + init("tool", loadInventory(inv).scopes[2]!.root); + return { base, bare, inv }; +} +const exec = (inv: string, op: string, args: unknown) => executeOperation(loadInventory(inv), op, args, "agent"); +type Row = { scope: string; stale: boolean; remoteFreshness: string }; +const row = (out: ReturnType, scope: string) => (out.data.remote as Row[]).find((r) => r.scope === scope)!; +const metaFile = (base: string, id: string) => join(base, ".mozak-cache", `${id}.meta.json`); + +test("local and vault-plans reads never fetch or write cache metadata", () => { + const { inv, base } = fixture(); + assert.equal(exec(inv, "context", { scope: "local" }).exitCode, 0); + assert.equal(exec(inv, "check", { scope: "local" }).exitCode, 0); + const vault = exec(inv, "context", { scope: "tool" }); + assert.equal(vault.exitCode, 0, JSON.stringify(vault.data.issues)); + assert.deepEqual(row(vault, "tool"), { scope: "tool", remote: `file://${join(base, "missing.git")}`, ref: "main", stale: false, lastFetchAt: null, source: "vault", remoteFreshness: "local" } as unknown as Row); + assert.equal(existsSync(metaFile(base, "tool")), false); + assert.equal(existsSync(metaFile(base, "local")), false); + assert.equal(existsSync(metaFile(base, "repo")), false, "no read touched the repo-mode scope"); +}); + +test("remote reads: fetched, then cached for ten minutes, then offline without retrying on every read", () => { + const { inv, base, bare } = fixture(); + assert.equal(row(exec(inv, "context", { scope: "repo" }), "repo").remoteFreshness, "fetched"); + assert.equal(row(exec(inv, "context", { scope: "repo" }), "repo").remoteFreshness, "cached"); + // Go offline and age the last fetch past the window. + rmSync(bare, { recursive: true }); + const meta = readRemoteMeta(base, "repo"); + writeRemoteMeta(base, "repo", { ...meta, lastFetchAt: new Date(Date.now() - 11 * 60_000).toISOString() }); + const first = exec(inv, "context", { scope: "repo" }); + assert.equal(first.exitCode, 0); + assert.deepEqual([row(first, "repo").stale, row(first, "repo").remoteFreshness], [true, "offline"]); + const afterFailure = readFileSync(metaFile(base, "repo"), "utf8"); + assert.ok(JSON.parse(afterFailure).lastAttemptAt); + // The next reads use the cached copy and do not try the network again: the metadata is untouched. + for (const op of ["context", "check", "plans"]) { + const out = exec(inv, op, op === "plans" ? { all: true } : { scope: "repo" }); + assert.equal(row(out, "repo").remoteFreshness, "offline", op); + assert.equal(readFileSync(metaFile(base, "repo"), "utf8"), afterFailure, `${op} did not retry the fetch`); + } + // sync always tries. + assert.equal(exec(inv, "sync", { scope: "repo" }).exitCode, 6); + assert.notEqual(readFileSync(metaFile(base, "repo"), "utf8"), afterFailure); + // Once the failed attempt is ten minutes old, a read tries again. + const m2 = readRemoteMeta(base, "repo"); + writeRemoteMeta(base, "repo", { ...m2, lastAttemptAt: new Date(Date.now() - 11 * 60_000).toISOString() }); + exec(inv, "context", { scope: "repo" }); + assert.ok(Date.parse(readRemoteMeta(base, "repo").lastAttemptAt!) > Date.now() - 60_000); +}); diff --git a/packages/core/test/s2-projection.test.ts b/packages/core/test/s2-projection.test.ts new file mode 100644 index 0000000..f565755 --- /dev/null +++ b/packages/core/test/s2-projection.test.ts @@ -0,0 +1,58 @@ +// S2 projection tolerance: a mozak.md that differs from the render only by CRLF line endings or trailing +// whitespace is not a bridge conflict. Synthetic temp scopes only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { readScope, normalizeProjection, renderProjection } from "../src/scope-store.ts"; + +after(cleanup); + +function setup() { + const w = world(); + w.propose("alpha", "first"); + const e = w.entries.alpha; + const path = join(e.root, "mozak.md"); + return { w, e, path, render: readFileSync(path, "utf8") }; +} + +test("CRLF line endings in mozak.md are not a bridge conflict, and the next write restores LF", () => { + const { w, e, path, render } = setup(); + assert.ok(render.includes("\n")); + writeFileSync(path, render.replace(/\n/g, "\r\n")); + const read = readScope(e); + assert.equal(read.projectionStatus, "current"); + assert.equal(read.issues.some((i) => i.code.startsWith("bridge-")), false); + w.propose("alpha", "second"); + const after = readFileSync(path, "utf8"); + assert.equal(after.includes("\r\n"), false); + assert.equal(readScope(e).projectionStatus, "current"); +}); + +test("trailing spaces, tabs and blank lines at the end are not a bridge conflict", () => { + const { w, e, path, render } = setup(); + writeFileSync(path, `${render.split("\n").map((l, i) => (i % 2 ? `${l} ` : `${l}\t`)).join("\n")}\n\n\n`); + assert.equal(readScope(e).projectionStatus, "current"); + assert.equal(renderProjection(e).result, "current"); + w.pass("alpha", "first", "done"); + assert.equal(readScope(e).projectionStatus, "current"); +}); + +test("missing final newline is tolerated, but any content edit is still a conflict", () => { + const { e, path, render } = setup(); + writeFileSync(path, render.replace(/\n+$/, "")); + assert.equal(readScope(e).projectionStatus, "current"); + writeFileSync(path, render.replace("Synthetic first work", "Synthetic first work")); + assert.equal(readScope(e).projectionStatus, "bridge-conflict", "inner whitespace is content"); + writeFileSync(path, ` ${render}`); + assert.equal(readScope(e).projectionStatus, "bridge-conflict", "leading whitespace is content"); + writeFileSync(path, `${render}extra line\n`); + assert.equal(readScope(e).projectionStatus, "bridge-conflict"); +}); + +test("normalizeProjection only touches line endings and trailing whitespace", () => { + assert.equal(normalizeProjection("a \r\nb\t\r\n\r\n"), "a\nb"); + assert.equal(normalizeProjection(" a b \n"), " a b"); + assert.equal(normalizeProjection("a\rb"), "a\rb", "a lone CR is content"); +}); diff --git a/packages/core/test/s2-prune.test.ts b/packages/core/test/s2-prune.test.ts new file mode 100644 index 0000000..6e232bb --- /dev/null +++ b/packages/core/test/s2-prune.test.ts @@ -0,0 +1,93 @@ +// S2 `plan prune --rejected`: owner removes rejected plans; the receipt is the prune record that refs resolve through. +// Synthetic temp scopes only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, content, world, NOW } from "./annotations-fixture.ts"; +import { readScope, validateScope } from "../src/index.ts"; +import { resolveRef } from "../src/annotations.ts"; +import { executeOperation } from "../src/api.ts"; + +after(cleanup); + +function setup() { + const w = world(["alpha", "beta"], { annotations: true }); + w.propose("alpha", "keep"); + w.propose("alpha", "dropped", {}, false); + w.reject("alpha", "dropped"); + w.propose("alpha", "dropped-too", {}, false); + w.reject("alpha", "dropped-too"); + w.propose("beta", "user"); + // An owner ref from another scope to the rejected plan, made while it still existed. + const annotated = w.annotate("beta", [{ kind: "ref", planId: "user", target: "alpha/dropped", relation: "needs", evidence: "synthetic evidence" }]); + assert.equal(annotated.exitCode, 0, JSON.stringify(annotated.data)); + const prune = (planIds: string[], actor: "owner" | "agent" = "owner", operationId = `prune-${planIds.join("+")}`) => + executeAs(w, { operationId, scopeId: "alpha", expected: readScope(w.entries.alpha).snapshot, planIds, ownerRef: "synthetic:owner-prune", ownerMessageAt: NOW }, actor); + return { w, prune }; +} +function executeAs(w: ReturnType, request: Record, actor: "owner" | "agent") { + return executeOperation(w.inv(), "prune", { scope: "alpha", request }, actor); +} + +test("prune removes only the listed rejected plans, leaves a receipt record, and refs resolve as pruned", () => { + const { w, prune } = setup(); + const before = readScope(w.entries.alpha); + const out = prune(["dropped"]); + assert.equal(out.exitCode, 0, JSON.stringify(out.data)); + const after = readScope(w.entries.alpha); + assert.deepEqual(after.state.plans.map((p) => p.id).sort(), ["dropped-too", "keep"]); + assert.notEqual(after.snapshot.revision, before.snapshot.revision, "a prune is a normal write with a new revision"); + const receipt = after.state.receipts["prune-dropped"]; + assert.deepEqual(receipt?.result, { action: "prune-rejected", ids: ["dropped"] }); + assert.equal(after.projectionStatus, "current"); + assert.doesNotThrow(() => validateScope(JSON.parse(readFileSync(join(w.entries.alpha.root, "mozak.json"), "utf8")))); + // S4 resolver: the pruned id resolves through its record, not as a dangling ref. + const lookup = (id: string) => (id === "alpha" ? after.state : id === "beta" ? readScope(w.entries.beta).state : "unknown" as const); + const r = resolveRef("alpha/dropped", lookup); + assert.equal(r.status, "pruned"); + assert.equal(r.status === "pruned" && r.prunedBy, "prune-dropped"); + assert.equal(resolveRef("alpha/never-existed", lookup).status, "dangling"); + const check = w.op("check", { scope: "beta" }); + const codes = (check.data.issues as { code: string }[]).map((i) => i.code); + assert.ok(codes.includes("ref-target-pruned"), codes.join(",")); + assert.equal(codes.includes("ref-dangling"), false); + const ready = w.op("ready", { scope: "beta" }); + const blocked = (ready.data.ready as { blocked: { planId: string; needs: { reason?: string }[] }[] }).blocked; + assert.equal(blocked.find((b) => b.planId === "user")?.needs[0]?.reason, "target rejected and pruned"); + const graph = w.op("graph", { scope: "beta" }); + assert.equal((graph.data.graph as { edges: { resolution: { status: string } }[] }).edges.filter((e) => e.resolution.status === "pruned").length, 1); + // The id stays reserved. + assert.throws(() => w.change("alpha", "propose", { planId: "dropped", content: content("dropped") }), /pruned rejected plan/); + // Replaying the same request is idempotent. + assert.equal(executeAs(w, { operationId: "prune-dropped", scopeId: "alpha", expected: before.snapshot, planIds: ["dropped"], ownerRef: "synthetic:owner-prune", ownerMessageAt: NOW }, "owner").data.status, "replayed"); +}); + +test("prune refuses agents, accepted plans, unknown ids, stale snapshots and empty lists, writing nothing", () => { + const { w, prune } = setup(); + const bytes = w.bytes("alpha"); + assert.equal(prune(["dropped"], "agent").data.status, "not-permitted"); + assert.equal(prune(["keep"]).data.status, "prune-not-rejected"); + assert.equal(prune(["dropped", "keep"]).data.status, "prune-not-rejected"); + assert.equal(prune(["nope"]).data.status, "stale-reference"); + assert.equal(prune([]).data.status, "invalid-input"); + const stale = { operationId: "prune-stale", scopeId: "alpha", expected: readScope(w.entries.alpha).snapshot, planIds: ["dropped"], ownerRef: "synthetic:owner-prune", ownerMessageAt: NOW }; + w.propose("alpha", "moves-revision"); + const newer = w.bytes("alpha"); + assert.equal(executeAs(w, stale, "owner").data.status, "stale-input", "prune is never rebased"); + assert.deepEqual(w.bytes("alpha"), newer); + assert.notDeepEqual(bytes, newer); +}); + +test("prune refuses a rejected plan another plan still references", () => { + const { w, prune } = setup(); + const target = w.plan("alpha", "keep"); + const merged = w.change("alpha", "revise", { planId: "keep", acceptedRevisionId: target.accepted!.id, pendingRevisionId: null, mergeFromPlanId: "dropped-too", content: content("keep", { title: "Unified keep" }) }); + assert.equal(merged.status, "ok"); + const bytes = w.bytes("alpha"); + const out = prune(["dropped", "dropped-too"]); + assert.equal(out.data.status, "prune-referenced"); + assert.match(JSON.stringify(out.data.issues), /dropped-too/); + assert.deepEqual(w.bytes("alpha"), bytes); + assert.equal(prune(["dropped"]).exitCode, 0); +}); diff --git a/packages/core/test/s2-recover.test.ts b/packages/core/test/s2-recover.test.ts new file mode 100644 index 0000000..a8ab02a --- /dev/null +++ b/packages/core/test/s2-recover.test.ts @@ -0,0 +1,135 @@ +// S2 recover: owner.json records host; the owner route clears a lock from another host or a dead local pid. +// Synthetic temp scopes only. Never run against a real inventory. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { hostname } from "node:os"; +import { join } from "node:path"; +import { cleanup, world, NOW } from "./annotations-fixture.ts"; +import { executeOperation } from "../src/api.ts"; +import { inspectLock, recoverLock } from "../src/lock-recover.ts"; +import { mutateScope, readScope } from "../src/scope-store.ts"; + +after(cleanup); + +const lockDir = (root: string) => join(root, ".mozak-write-lock"); +function plantLock(root: string, owner: Record) { + mkdirSync(lockDir(root)); + writeFileSync(join(lockDir(root), "owner.json"), JSON.stringify(owner)); +} +/** A pid that certainly belonged to a process on this host and has exited. */ +function deadPid(): number { + const r = spawnSync(process.execPath, ["-e", "process.stdout.write(String(process.pid))"], { encoding: "utf8" }); + return Number(r.stdout); +} +const request = (scopeId: string, lock: { token: string; host: string; pid: number }, requestId = "recover-1") => + ({ requestId, scopeId, lock, ownerRef: "synthetic:owner-recover", ownerMessageAt: NOW }); + +test("owner.json records the host while a write holds the lock", () => { + const w = world(); + let seen: Record | null = null; + const e = w.entries.alpha; + mutateScope(e, { operationId: "p1", scopeId: "alpha", expected: readScope(e).snapshot, action: "propose", payload: { planId: "p", content: { constraints: [], nonGoals: [], outcomes: [{ acceptance: "objective", criterion: "c", id: "o", statement: "s" }], purpose: "p", questions: [], rationale: "r", sources: [], title: "t" } } }, "agent", { + onPhase(phase) { if (phase === "after-lock") seen = JSON.parse(readFileSync(join(lockDir(e.root), "owner.json"), "utf8")); }, + }); + assert.ok(seen); + assert.equal(seen!.host, hostname()); + assert.equal(seen!.pid, process.pid); + assert.equal(existsSync(lockDir(e.root)), false); +}); + +test("recover clears a lock that names another host, and writes work again", () => { + const w = world(); + const e = w.entries.alpha; + const lock = { token: "tok-other", host: "synthetic-other-host", pid: process.pid }; + plantLock(e.root, { ...lock, processStartHint: NOW, acquiredAt: NOW }); + const before = readFileSync(join(e.root, "mozak.json")); + const blocked = executeOperation(w.inv(), "propose", { scope: "alpha", request: { operationId: "x1", scopeId: "alpha", expected: readScope(e).snapshot, action: "propose", payload: {} } }, "agent"); + assert.notEqual(blocked.exitCode, 0); + const check = executeOperation(w.inv(), "check", { scope: "alpha" }, "agent"); + const finding = (check.data.issues as { code: string; lock?: { verdict: string; token: string } }[]).find((i) => i.code === "write-lock-stuck"); + assert.equal(finding?.lock?.verdict, "other-host"); + assert.equal(finding?.lock?.token, "tok-other"); + assert.equal(check.exitCode, 3); + // Agents can never recover. + const agent = executeOperation(w.inv(), "recover", { scope: "alpha", request: request("alpha", lock) }, "agent"); + assert.equal(agent.data.status, "not-permitted"); + assert.equal(existsSync(lockDir(e.root)), true); + const out = executeOperation(w.inv(), "recover", { scope: "alpha", request: request("alpha", lock) }, "owner"); + assert.equal(out.exitCode, 0, JSON.stringify(out.data)); + assert.equal(out.data.status, "ok"); + assert.equal(out.data.reason, "other-host"); + assert.equal(existsSync(lockDir(e.root)), false); + assert.deepEqual(readFileSync(join(e.root, "mozak.json")), before, "recover never touches mozak.json"); + assert.equal(readdirSync(e.root).some((n) => n.startsWith(".mozak-write-lock")), false); + // Running the same request again is harmless. + assert.equal(executeOperation(w.inv(), "recover", { scope: "alpha", request: request("alpha", lock) }, "owner").data.status, "already-clear"); + w.propose("alpha", "after-recover"); + assert.equal(executeOperation(w.inv(), "check", { scope: "alpha" }, "agent").exitCode, 0); +}); + +test("recover clears a lock from a dead local pid but refuses a live local pid", () => { + const w = world(); + const e = w.entries.alpha; + const dead = { token: "tok-dead", host: hostname(), pid: deadPid() }; + plantLock(e.root, { ...dead, processStartHint: NOW, acquiredAt: NOW }); + assert.equal(inspectLock(e.root).verdict, "dead-local-pid"); + const ok = recoverLock(e, request("alpha", dead)); + assert.equal(ok.status, "ok"); + assert.equal(ok.reason, "dead-local-pid"); + assert.equal(existsSync(lockDir(e.root)), false); + + const live = { token: "tok-live", host: hostname(), pid: process.pid }; + plantLock(e.root, { ...live, processStartHint: NOW, acquiredAt: NOW }); + const refused = executeOperation(w.inv(), "recover", { scope: "alpha", request: request("alpha", live) }, "owner"); + assert.equal(refused.data.status, "lock-owner-alive"); + assert.equal(refused.exitCode, 4); + assert.equal(existsSync(join(lockDir(e.root), "owner.json")), true); + // A live local holder is informational in check, not a finding. + const check = executeOperation(w.inv(), "check", { scope: "alpha" }, "agent"); + assert.equal((check.data.issues as { code: string }[]).some((i) => i.code === "write-lock-held"), true); + assert.equal((check.data.issues as { code: string }[]).some((i) => i.code === "write-lock-stuck"), false); +}); + +test("recover refuses a changed lock, extra contents, a hostless lock and malformed requests", () => { + const w = world(); + const e = w.entries.alpha; + const lock = { token: "tok-a", host: "synthetic-other-host", pid: 4242 }; + plantLock(e.root, { ...lock, processStartHint: NOW, acquiredAt: NOW }); + const run = (r: unknown) => executeOperation(w.inv(), "recover", { scope: "alpha", request: r }, "owner"); + assert.equal(run(request("alpha", { ...lock, token: "tok-b" })).data.status, "lock-changed"); + assert.equal(run(request("alpha", { ...lock, host: "elsewhere" })).data.status, "lock-changed"); + assert.equal(run(request("beta", lock)).data.status, "scope-mismatch"); + assert.equal(run({ ...request("alpha", lock), extra: 1 }).data.status, "invalid-input"); + assert.equal(run({ requestId: "r", scopeId: "alpha", lock: { token: "tok-a", host: "h" }, ownerRef: "o", ownerMessageAt: NOW }).data.status, "invalid-input"); + writeFileSync(join(lockDir(e.root), "unexpected.txt"), "keep\n"); + assert.equal(run(request("alpha", lock)).data.status, "lock-unexpected-contents"); + assert.equal(readFileSync(join(lockDir(e.root), "unexpected.txt"), "utf8"), "keep\n"); + + const w2 = world(); + const e2 = w2.entries.alpha; + plantLock(e2.root, { token: "tok-old", pid: 4242, processStartHint: NOW, acquiredAt: NOW }); + const old = executeOperation(w2.inv(), "recover", { scope: "alpha", request: request("alpha", { token: "tok-old", host: "x", pid: 4242 }) }, "owner"); + assert.equal(old.data.status, "lock-changed", "a hostless lock never matches a named host"); + assert.equal(inspectLock(e2.root).verdict, "host-unknown"); + assert.equal(existsSync(lockDir(e2.root)), true); +}); + +test("recover restores the lock untouched if it was replaced between inspection and rename", () => { + const w = world(); + const e = w.entries.alpha; + const lock = { token: "tok-first", host: "synthetic-other-host", pid: 7 }; + plantLock(e.root, { ...lock, processStartHint: NOW, acquiredAt: NOW }); + let calls = 0; + // The probe runs at the end of the first inspection: the owner file is swapped before the rename. + const probe = { + hostname: () => { + calls++; + if (calls === 1) writeFileSync(join(lockDir(e.root), "owner.json"), JSON.stringify({ token: "tok-second", host: "synthetic-other-host", pid: 7 })); + return hostname(); + }, + }; + assert.throws(() => recoverLock(e, request("alpha", lock), probe), { code: "lock-changed" }); + assert.equal(JSON.parse(readFileSync(join(lockDir(e.root), "owner.json"), "utf8")).token, "tok-second"); +}); diff --git a/packages/core/test/s2-sync.test.ts b/packages/core/test/s2-sync.test.ts new file mode 100644 index 0000000..5d70997 --- /dev/null +++ b/packages/core/test/s2-sync.test.ts @@ -0,0 +1,135 @@ +// S2 `mozak sync` for local scopes in a git repo: fetch outside the locks, take every scope lock in the repo in path +// order, `git merge --ff-only`, release; abort on a diverged history. Local bare repos in temp dirs only, never GitHub. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { executeOperation, initScopeState, loadInventory, readScope } from "../src/index.ts"; +import { syncLocal } from "../src/local-sync.ts"; + +const scratch = process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(); +const made: string[] = []; +after(() => { for (const d of made) { if (!d.includes("/mozak-s2sync-")) throw new Error(d); rmSync(d, { recursive: true, force: true }); } }); +const g = (cwd: string, ...args: string[]) => + execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", "-c", "protocol.file.allow=always", ...args], { cwd, encoding: "utf8", env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }).trim(); +const content = (title: string) => ({ constraints: [], nonGoals: [], outcomes: [{ acceptance: "objective", criterion: "c", id: "o", statement: "s" }], purpose: "p", questions: [], rationale: "r", sources: [], title }); + +function fixture() { + const base = mkdtempSync(join(scratch, "mozak-s2sync-")); + made.push(base); + const bare = join(base, "vault.git"); + const seed = join(base, "seed"); + g(base, "init", "--bare", "-b", "main", bare); + mkdirSync(seed); + g(seed, "init", "-b", "main"); + for (const id of ["s1", "s2"]) { + const root = join(seed, "notes", id); + mkdirSync(root, { recursive: true }); + writeFileSync(join(root, "README.md"), "# r\n"); + writeFileSync(join(root, "AGENTS.md"), "# a\n"); + initScopeState({ id, root }, { operationId: `init-${id}`, scopeId: id, kind: "project", title: id, expectedAbsent: { graph: true, bridge: true }, ownerRef: "host:t", ownerMessageAt: "2026-10-12T08:50:00.000Z" }); + } + writeFileSync(join(seed, "other.md"), "a vault note\n"); + g(seed, "add", "."); g(seed, "commit", "-q", "-m", "seed"); g(seed, "remote", "add", "origin", bare); g(seed, "push", "-q", "-u", "origin", "main"); + const clone = (name: string) => { + const dir = join(base, name); + g(base, "clone", "-q", bare, dir); + const inv = join(base, `${name}-inventory.json`); + writeFileSync(inv, JSON.stringify({ format: "mozak.local/v3", scopes: [{ id: "s1", root: join(dir, "notes", "s1") }, { id: "s2", root: join(dir, "notes", "s2") }] })); + return { dir, inv }; + }; + return { base, bare, a: clone("a"), b: clone("b") }; +} +const exec = (inv: string, op: string, args: unknown) => executeOperation(loadInventory(inv), op, args, "agent"); +function pushChange(side: { dir: string; inv: string }, planId: string) { + const scope = "s1"; + const entry = loadInventory(side.inv).scopes[0]!; + const out = exec(side.inv, "propose", { scope, request: { operationId: `op-${planId}`, scopeId: scope, expected: readScope(entry).snapshot, action: "propose", payload: { planId, content: content(planId) } } }); + assert.equal(out.exitCode, 0, JSON.stringify(out.data)); + g(side.dir, "add", "-A"); g(side.dir, "commit", "-q", "-m", `plan ${planId}`); g(side.dir, "push", "-q"); +} + +test("sync --scope LOCAL fast-forwards the vault under every scope lock in path order, then is up to date", () => { + const { a, b } = fixture(); + pushChange(b, "from-b"); + const inv = loadInventory(a.inv); + const seen: string[][] = []; + const rows = syncLocal([inv.scopes[0]!], inv.scopes, { + onPhase(phase) { if (phase === "sync-locked") seen.push(["s1", "s2"].filter((id) => existsSync(join(a.dir, "notes", id, ".mozak-write-lock")))); }, + }); + assert.equal(rows.length, 1); + assert.equal(rows[0]!.status, "fast-forwarded", JSON.stringify(rows)); + assert.deepEqual(rows[0]!.locked, ["s1", "s2"]); + assert.deepEqual(seen, [["s1", "s2"]], "both scope locks were held during the merge"); + assert.equal(existsSync(join(a.dir, "notes", "s1", ".mozak-write-lock")) || existsSync(join(a.dir, "notes", "s2", ".mozak-write-lock")), false, "locks released"); + assert.equal(readFileSync(join(a.dir, "notes", "s1", "mozak.json"), "utf8"), readFileSync(join(b.dir, "notes", "s1", "mozak.json"), "utf8")); + assert.equal(g(a.dir, "rev-parse", "HEAD"), g(b.dir, "rev-parse", "HEAD")); + const again = exec(a.inv, "sync", { scope: "s2" }); + assert.equal(again.exitCode, 0); + assert.equal((again.data.local as { status: string }[])[0]!.status, "up-to-date"); + // An agent reading after sync sees the new plan. + assert.ok(readScope(inv.scopes[0]!).state.plans.some((p) => p.id === "from-b")); +}); + +test("sync aborts on a diverged history and changes nothing", () => { + const { a, b } = fixture(); + pushChange(b, "from-b"); + // A commits its own change without pushing. + pushChangeLocalOnly(a, "from-a"); + const head = g(a.dir, "rev-parse", "HEAD"); + const bytes = readFileSync(join(a.dir, "notes", "s1", "mozak.json")); + const out = exec(a.inv, "sync", { scope: "s1" }); + assert.equal(out.data.status, "local-sync-not-fast-forward"); + assert.equal(out.exitCode, 3); + assert.equal(g(a.dir, "rev-parse", "HEAD"), head); + assert.deepEqual(readFileSync(join(a.dir, "notes", "s1", "mozak.json")), bytes); + assert.equal(g(a.dir, "status", "--porcelain"), ""); +}); +function pushChangeLocalOnly(side: { dir: string; inv: string }, planId: string) { + const entry = loadInventory(side.inv).scopes[0]!; + exec(side.inv, "propose", { scope: "s1", request: { operationId: `op-${planId}`, scopeId: "s1", expected: readScope(entry).snapshot, action: "propose", payload: { planId, content: content(planId) } } }); + g(side.dir, "add", "-A"); g(side.dir, "commit", "-q", "-m", `plan ${planId}`); +} + +test("sync refuses while any scope lock in the repo is held, releases what it took, and reports ahead and fetch failures", () => { + const { a, b, bare } = fixture(); + pushChange(b, "from-b"); + const lock = join(a.dir, "notes", "s2", ".mozak-write-lock"); + mkdirSync(lock); + writeFileSync(join(lock, "owner.json"), JSON.stringify({ token: "held", pid: process.pid, host: "elsewhere" })); + const head = g(a.dir, "rev-parse", "HEAD"); + const busy = exec(a.inv, "sync", { scope: "s1" }); + assert.equal(busy.data.status, "local-sync-busy"); + assert.equal(busy.exitCode, 4); + assert.equal(g(a.dir, "rev-parse", "HEAD"), head); + assert.equal(existsSync(join(a.dir, "notes", "s1", ".mozak-write-lock")), false, "the s1 lock taken first was released"); + rmSync(lock, { recursive: true }); + // --local syncs every local repo (and remotes, none here). + const all = exec(a.inv, "sync", { local: true }); + assert.equal(all.exitCode, 0, JSON.stringify(all.data)); + assert.equal((all.data.local as { status: string }[])[0]!.status, "fast-forwarded"); + // Local commits not yet pushed: nothing to merge, reported as ahead. + pushChangeLocalOnly(a, "only-a"); + assert.equal((exec(a.inv, "sync", { scope: "s1" }).data.local as { status: string }[])[0]!.status, "ahead"); + rmSync(bare, { recursive: true }); + const offline = exec(a.inv, "sync", { scope: "s1" }); + assert.equal((offline.data.local as { status: string }[])[0]!.status, "fetch-failed"); + assert.equal(offline.exitCode, 6); + assert.equal(exec(a.inv, "sync", { scope: "s1", local: true }).data.status, "invalid-input"); +}); + +test("sync of a local scope outside git reports not-in-git", () => { + const base = mkdtempSync(join(scratch, "mozak-s2sync-")); + made.push(base); + const root = join(base, "plain"); + mkdirSync(root); + writeFileSync(join(root, "README.md"), "# r\n"); writeFileSync(join(root, "AGENTS.md"), "# a\n"); + initScopeState({ id: "plain", root }, { operationId: "init", scopeId: "plain", kind: "project", title: "p", expectedAbsent: { graph: true, bridge: true }, ownerRef: "host:t", ownerMessageAt: "2026-10-12T08:50:00.000Z" }); + const inv = join(base, "inventory.json"); + writeFileSync(inv, JSON.stringify({ format: "mozak.local/v3", scopes: [{ id: "plain", root }] })); + const out = exec(inv, "sync", { scope: "plain" }); + assert.equal(out.data.status, "local-sync-not-in-git"); + assert.equal(out.exitCode, 2); +}); diff --git a/packages/core/test/s2-usage.test.ts b/packages/core/test/s2-usage.test.ts new file mode 100644 index 0000000..b1f2c87 --- /dev/null +++ b/packages/core/test/s2-usage.test.ts @@ -0,0 +1,142 @@ +// S2 usage log and monthly aggregates. Synthetic temp dirs only; never writes to a real vault. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, mkdirSync, readFileSync, readdirSync, symlinkSync } from "node:fs"; +import { join } from "node:path"; +import { execFileSync } from "node:child_process"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { aggregateUsage, appendUsage, monthOf, readUsageLines, usageDir, usageHost, usageLine, usageLogEnabled, usageLogPath, writeUsageAggregate, type UsageLine } from "../src/usage.ts"; +import { executeOperation } from "../src/api.ts"; +import { readScope } from "../src/scope-store.ts"; + +after(cleanup); + +/** Runs fn with MOZAK_USAGE_LOG set to value (undefined: unset), then restores it. */ +function withUsageEnv(value: string | undefined, fn: () => T): T { + const before = process.env.MOZAK_USAGE_LOG; + if (value === undefined) delete process.env.MOZAK_USAGE_LOG; else process.env.MOZAK_USAGE_LOG = value; + try { return fn(); } finally { if (before === undefined) delete process.env.MOZAK_USAGE_LOG; else process.env.MOZAK_USAGE_LOG = before; } +} + +test("the usage log is off by default: no env and no setting write nothing next to the inventory", () => { + for (const settings of [undefined, { format: "mozak.settings/v1" }]) { + const w = world(["alpha"], { settings }); + withUsageEnv(undefined, () => { + executeOperation(w.inv(), "context", { scope: "alpha" }); + executeOperation(w.inv(), "plans", { all: true }); + }); + assert.equal(existsSync(usageDir(w.base)), false, JSON.stringify(settings)); + } +}); + +test("usageLog true in mozak-settings.json turns the log on; MOZAK_USAGE_LOG=off still wins", () => { + const w = world(["alpha"], { settings: { format: "mozak.settings/v1", usageLog: true } }); + withUsageEnv(undefined, () => executeOperation(w.inv(), "context", { scope: "alpha" })); + assert.equal(readUsageLines(w.base, monthOf(new Date())).length, 1); + withUsageEnv("off", () => executeOperation(w.inv(), "context", { scope: "alpha" })); + assert.equal(readUsageLines(w.base, monthOf(new Date())).length, 1); + assert.deepEqual(executeOperation(w.inv(), "check", { scope: "alpha" }).data.issues, []); +}); + +test("a usageLog that is not a boolean makes the settings file invalid: nothing is logged and check reports it", () => { + const w = world(["alpha"], { settings: { format: "mozak.settings/v1", usageLog: "yes" } }); + withUsageEnv(undefined, () => executeOperation(w.inv(), "context", { scope: "alpha" })); + assert.equal(existsSync(usageDir(w.base)), false); + const issues = executeOperation(w.inv(), "check", { scope: "alpha" }).data.issues as { code: string; message: string }[]; + assert.ok(issues.some((i) => i.code === "settings-invalid" && i.message.includes("usageLog")), JSON.stringify(issues)); +}); + +test("usageLogEnabled: only on, 1 or true turn it on, an explicit off value wins over the setting", () => { + for (const v of ["on", "1", "true", " ON "]) assert.equal(usageLogEnabled({ MOZAK_USAGE_LOG: v }), true, v); + for (const v of [undefined, "", "0", "off", "false", "yes"]) assert.equal(usageLogEnabled({ MOZAK_USAGE_LOG: v }), false, String(v)); + assert.equal(usageLogEnabled({}, true), true); + for (const v of ["0", "off", "false"]) assert.equal(usageLogEnabled({ MOZAK_USAGE_LOG: v }, true), false, v); +}); + +test("every operation appends one counts-only line next to the inventory, never request or plan text", () => { + const w = world(); + w.propose("alpha", "secret-plan-id", { title: "TOP SECRET TITLE", purpose: "PRIVATE PURPOSE" }); + const inv = w.inv(); + withUsageEnv("on", () => { + executeOperation(inv, "context", { scope: "alpha" }); + executeOperation(inv, "plans", { all: true }); + executeOperation(inv, "observe", { scope: "alpha", request: { operationId: "x", scopeId: "alpha", expected: { ...readScope(w.entries.alpha).snapshot, revision: "old" }, action: "observe", payload: { planId: "secret-plan-id" } } }); + }); + const base = w.base; + const month = monthOf(new Date()); + const lines = readUsageLines(base, month); + assert.equal(lines.length, 3); + assert.deepEqual(lines.map((l) => [l.op, l.scope, l.exit]), [["context", "alpha", 0], ["plans", "all", 0], ["observe", "alpha", lines[2]!.exit]]); + for (const l of lines) { + assert.deepEqual(Object.keys(l).filter((k) => !["v", "ts", "host", "actor", "op", "scope", "exit", "status", "ms", "bytes", "committed", "rebased"].includes(k)), []); + assert.ok(l.bytes > 0); + } + const raw = readFileSync(usageLogPath(base, month), "utf8"); + for (const secret of ["TOP SECRET TITLE", "PRIVATE PURPOSE", "secret-plan-id", "operationId"]) assert.equal(raw.includes(secret), false, secret); + // The folder ignores itself, so a cache inside a vault is never committed. + assert.equal(readFileSync(join(usageDir(base), ".gitignore"), "utf8"), "*\n"); + execFileSync("git", ["init", "-q", base]); + assert.equal(execFileSync("git", ["status", "--porcelain", "--untracked-files=all", "--", ".mozak-cache"], { cwd: base, encoding: "utf8" }), ""); +}); + +test("MOZAK_USAGE_LOG=0 keeps the log off; inventories without a file path never log", () => { + const w = world(); + withUsageEnv("0", () => executeOperation(w.inv(), "context", { scope: "alpha" })); + assert.equal(existsSync(usageDir(w.base)), false); + const inv = w.inv(); + const plain = { format: inv.format, scopes: inv.scopes, digest: inv.digest }; + withUsageEnv("on", () => executeOperation(plain, "context", { scope: "alpha" })); + assert.equal(existsSync(usageDir(w.base)), false); +}); + +test("aggregateUsage counts per operation, exit and status, stale refusals and writes, without scope ids", () => { + const mk = (op: string, exit: number, status: string, ms: number, extra: Partial = {}): UsageLine => ({ v: 1, ts: "2026-10-03T10:00:00.000Z", host: "h", actor: "agent", op, scope: "private-scope", exit, status, ms, bytes: 100, ...extra }); + const lines = [mk("observe", 0, "ok", 40, { committed: true }), mk("observe", 3, "stale-input", 5), mk("observe", 0, "ok", 60, { committed: true, rebased: true }), mk("context", 0, "ok", 10, { actor: "owner" }), { ...mk("context", 0, "ok", 1), ts: "2026-09-30T23:59:59.000Z" }]; + const agg = aggregateUsage(lines, "h", "2026-10"); + assert.equal(agg.calls, 4); + assert.equal(agg.writes, 2); + assert.equal(agg.staleRefusals, 1); + assert.equal(agg.rebased, 1); + assert.deepEqual(agg.byActor, { agent: 3, owner: 1 }); + assert.deepEqual(Object.keys(agg.byOperation), ["context", "observe"]); + assert.deepEqual(agg.byOperation.observe, { calls: 3, exits: { 0: 2, 3: 1 }, statuses: { ok: 2, "stale-input": 1 }, msP50: 40, msP95: 60, bytesTotal: 300 }); + assert.equal(JSON.stringify(agg).includes("private-scope"), false); +}); + +test("writeUsageAggregate writes -.json and refuses scope or index roots", () => { + const w = world(); + const line = usageLine("context", { scope: "alpha" }, "agent", { status: "ok" }, 0, 3, new Date("2026-10-05T00:00:00Z")); + assert.equal(appendUsage(w.base, line), true); + const agg = aggregateUsage(readUsageLines(w.base, "2026-10"), usageHost(), "2026-10"); + assert.equal(agg.calls, 1); + const vault = join(w.base, "personal-vault"); + mkdirSync(vault); + const target = join(vault, ".mozak-usage"); + const path = writeUsageAggregate(target, agg, [w.entries.alpha.root]); + assert.ok(path.endsWith(`/.mozak-usage/${usageHost()}-2026-10.json`), path); + assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), agg); + assert.deepEqual(readdirSync(target), [`${usageHost()}-2026-10.json`]); + // Rewriting the same month replaces the file. + writeUsageAggregate(target, { ...agg, calls: 2 }, []); + assert.equal(JSON.parse(readFileSync(path, "utf8")).calls, 2); + assert.throws(() => writeUsageAggregate(join(w.entries.alpha.root, ".mozak-usage"), agg, [w.entries.alpha.root]), { code: "usage-target-refused" }); + assert.throws(() => writeUsageAggregate(w.base, agg, [w.entries.alpha.root]), { code: "usage-target-refused" }, "a folder that contains a scope is refused too"); + assert.throws(() => writeUsageAggregate(target, { ...agg, month: "2026-1" }, []), { code: "invalid-input" }); +}); + +test("a not-yet-created aggregate below a symlinked scope is refused", () => { + const w = world(); + const alias = join(w.base, "scope-alias"); + symlinkSync(w.entries.alpha.root, alias, "dir"); + const agg = aggregateUsage([], "synthetic", "2026-10"); + assert.throws(() => writeUsageAggregate(join(alias, "new", ".mozak-usage"), agg, [w.entries.alpha.root]), { code: "usage-target-refused" }); + assert.equal(existsSync(join(w.entries.alpha.root, "new")), false); +}); + +test("a torn last line is skipped when reading the log", () => { + const w = world(); + const line = usageLine("check", { scope: "alpha" }, "agent", { status: "ok" }, 0, 1, new Date("2026-11-01T00:00:00Z")); + appendUsage(w.base, line); + execFileSync("sh", ["-c", `printf '{"v":1,"ts":"2026-11' >> "${usageLogPath(w.base, "2026-11")}"`]); + assert.equal(readUsageLines(w.base, "2026-11").length, 1); +}); diff --git a/packages/core/test/s6-fixture.ts b/packages/core/test/s6-fixture.ts new file mode 100644 index 0000000..b35c2f6 --- /dev/null +++ b/packages/core/test/s6-fixture.ts @@ -0,0 +1,77 @@ +// Synthetic temp vaults for S6 tests (plans.md, locators, cited-note staleness). Never touches a real inventory. +// Layout: /vault is one git repo with scopes under personal/ and research/; /company is a second git +// repo whose scope sits at the repo root, like a shared company vault. +import { execFileSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { initScopeState, mutateScope, readScope } from "../src/scope-store.ts"; +import { reviewShow } from "../src/review.ts"; +import { executeOperation } from "../src/api.ts"; +import { loadInventory } from "../src/scope-index.ts"; + +export const NOW = "2026-10-20T09:00:00.000Z"; +const roots: string[] = []; +export function cleanupS6() { for (const r of roots.splice(0)) rmSync(r, { recursive: true, force: true }); } + +export function git(dir: string, args: string[], date?: string) { + const env = { ...process.env, GIT_AUTHOR_NAME: "Synthetic", GIT_AUTHOR_EMAIL: "synthetic@example.invalid", GIT_COMMITTER_NAME: "Synthetic", GIT_COMMITTER_EMAIL: "synthetic@example.invalid", ...(date ? { GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date } : {}) }; + return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", env, timeout: 10000 }); +} + +export interface SourceSpec { locator: string; anchor?: string | null; observedAt?: string } +export interface S6PlanSpec { title?: string; purpose?: string; outcomes?: { id: string; statement?: string }[]; sources?: SourceSpec[] } + +export const s6content = (id: string, spec: S6PlanSpec = {}) => ({ + constraints: [], + nonGoals: [], + outcomes: (spec.outcomes ?? [{ id: "done" }]).map((o) => ({ acceptance: "objective", criterion: "Synthetic check passes", id: o.id, statement: o.statement ?? `Outcome ${o.id} of ${id}` })), + purpose: spec.purpose ?? `Exercise synthetic plan ${id}`, + questions: [], + rationale: `Synthetic rationale for ${id}`, + sources: (spec.sources ?? []).map((s, i) => ({ id: `s${i + 1}`, locator: s.locator, anchor: s.anchor ?? null, observedAt: s.observedAt ?? NOW, version: null, limitations: [] })), + title: spec.title ?? `Synthetic ${id} work`, +}); + +/** scopes: id -> folder relative to base (for example "vault/personal/p"). */ +export function s6world(scopes: Record, options: { repos?: string[]; settings?: unknown } = {}) { + const base = mkdtempSync(join(process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(), "mozak-s6-")); + roots.push(base); + for (const repo of options.repos ?? []) { + mkdirSync(join(base, repo), { recursive: true }); + execFileSync("git", ["init", "-q", join(base, repo)], { timeout: 5000 }); + } + const entries: Record = {}; + for (const [id, rel] of Object.entries(scopes)) { + const root = join(base, rel); + mkdirSync(root, { recursive: true }); + writeFileSync(join(root, "README.md"), "Synthetic scope\n"); + writeFileSync(join(root, "AGENTS.md"), "Synthetic instructions\n"); + entries[id] = { id, root }; + initScopeState(entries[id], { operationId: `init-${id}`, scopeId: id, kind: "project", title: `Synthetic ${id} scope`, expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic:init", ownerMessageAt: NOW }); + } + const config = join(base, "inventory.json"); + writeFileSync(config, JSON.stringify({ format: "mozak.local/v3", scopes: Object.keys(scopes).map((id) => ({ id, root: entries[id].root })) })); + if (options.settings !== undefined) writeFileSync(join(base, "mozak-settings.json"), JSON.stringify(options.settings)); + let seq = 0; + const inv = () => loadInventory(config); + const change = (scope: string, action: string, payload: unknown, actor: "agent" | "owner" = "agent") => + mutateScope(entries[scope], { operationId: `op-${++seq}`, scopeId: scope, expected: readScope(entries[scope]).snapshot, action, payload }, actor); + const decide = (scope: string, planId: string, purpose: "approve-direction" | "reject-pending", reason = "Synthetic decision") => { + const shown = reviewShow(readScope(entries[scope]).state, planId, purpose); + return change(scope, purpose, { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: `synthetic:${purpose}-${++seq}`, ownerMessageAt: NOW, reason }, "owner"); + }; + const propose = (scope: string, planId: string, spec: S6PlanSpec = {}, then: "approve" | "reject" | "await" = "approve", reason?: string) => { + change(scope, "propose", { planId, content: s6content(planId, spec), distinctFromPlanIds: readScope(entries[scope]).state.plans.map((p) => p.id) }); + if (then === "approve") decide(scope, planId, "approve-direction"); + if (then === "reject") decide(scope, planId, "reject-pending", reason); + }; + const observe = (scope: string, planId: string, locator: string, inspectedAt: string, anchor: string | null = null) => { + const p = readScope(entries[scope]).state.plans.find((x) => x.id === planId)!; + const id = `obs-${++seq}`; + const evidence = { id: `${id}-e`, locator, anchor, version: null, inspectedAt, activity: { kind: "read", description: "synthetic read" }, result: { verdict: "pass", summary: "passed" }, limitations: [] }; + return change(scope, "observe", { planId, observation: { id, classification: "observed", summary: id, evidence: [evidence] }, reasoningLinks: [{ id: `${id}-link`, relation: "supports", from: { planId, revisionId: null, kind: "observation", id }, to: { planId, revisionId: p.accepted!.id, kind: "outcome", id: p.accepted!.content.outcomes[0].id }, rationale: "synthetic" }] }); + }; + const op = (operation: string, args: Record, actor: "agent" | "owner" = "agent") => executeOperation(inv(), operation, args, actor); + return { base, config, entries, inv, change, decide, propose, observe, op }; +} diff --git a/packages/core/test/s6-index.test.ts b/packages/core/test/s6-index.test.ts new file mode 100644 index 0000000..a169b1e --- /dev/null +++ b/packages/core/test/s6-index.test.ts @@ -0,0 +1,206 @@ +// S6: Croatian folding, fence-aware wikilinks, indexRoots settings, locator resolution, cited-note staleness in check, +// plans.md and the include-private usage flag. Synthetic temp vaults only. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanupS6, git, s6world } from "./s6-fixture.ts"; +import { foldText } from "../src/fold.ts"; +import { stripCode, wikiLinks } from "../src/notes.ts"; +import { loadSettings } from "../src/settings.ts"; +import { anchoredSection, defaultIndexRoots, LocatorResolver, noteTitle } from "../src/locators.ts"; +import { PLANS_INDEX_MARKER } from "../src/plans-index.ts"; +import { readUsageLines } from "../src/usage.ts"; + +after(cleanupS6); +type Issue = { code: string; message: string; planId?: string; path?: string; source?: string }; + +test("Croatian folding maps č ć š ž đ in both cases and leaves other letters", () => { + assert.equal(foldText("Čćšžđ ČĆŠŽĐ ñ é"), "Ccszd CCSZD ñ é"); +}); + +test("wikilinks skip fenced blocks and code spans, and keep anchors without aliases", () => { + const text = ["See [[Alpha note#Plan|the plan]] and ![[embed.png]].", "```", "[[Inside fence]]", "```", "~~~md", "[[Tilde fence]]", "~~~", "Inline `[[In code]]` and [[Beta]] again [[Beta]]."].join("\n"); + assert.deepEqual(wikiLinks(text), [{ target: "Alpha note", anchor: "Plan" }, { target: "embed.png", anchor: null }, { target: "Beta", anchor: null }]); + assert.ok(!stripCode(text).includes("Inside fence")); +}); + +test("indexRoots: parsed relative to the settings file; unknown item keys and scope-level indexRoots are reported", () => { + const w = s6world({ a: "vault/research/a" }, { repos: ["vault"], settings: { format: "mozak.settings/v1", indexRoots: [{ path: "vault/personal", private: true, extra: 1 }, { path: "vault/research" }], scopes: { a: { indexRoots: [] } } } }); + const s = loadSettings(w.inv()); + assert.deepEqual(s.indexRoots?.map((r) => [r.path.endsWith(join("vault", "personal")), r.private]), [[true, true], [false, false]]); + assert.deepEqual(s.issues.map((i) => i.message.match(/"([^"]+)"/)?.[1]), ["indexRoots[0].extra", "scopes.a.indexRoots"]); + writeFileSync(join(w.base, "mozak-settings.json"), JSON.stringify({ format: "mozak.settings/v1", indexRoots: [{ path: 3 }] })); + assert.throws(() => loadSettings(w.inv()), { code: "settings-invalid" }); + const check = w.op("check", { scope: "a" }); + assert.ok((check.data.issues as Issue[]).some((i) => i.code === "settings-invalid")); +}); + +test("default index roots: top folders of a vault repo holding scopes, personal private, a scope at a repo root is not a root", () => { + const w = s6world({ me: "vault/personal/me", lab: "vault/research/lab", co: "company" }, { repos: ["vault", "company"] }); + const roots = defaultIndexRoots(w.inv()); + assert.deepEqual(roots.map((r) => [r.path.split("/").slice(-2).join("/"), r.private]), [["vault/personal", true], ["vault/research", false]]); +}); + +function locatorWorld() { + const w = s6world({ me: "vault/personal/me", lab: "vault/research/lab", co: "company" }, { repos: ["vault", "company"] }); + const v = join(w.base, "vault"); + mkdirSync(join(v, "research", "notes"), { recursive: true }); + writeFileSync(join(v, "research", "notes", "Đakovo trip.md"), "---\ntags: x\n---\n# Trip to Đakovo\n\nIntro line.\n\n## Budget and costs\n\nCosts are low.\n\n```\n## Not a heading\n```\n"); + writeFileSync(join(v, "research", "notes", "dup.md"), "# Dup one\n"); + mkdirSync(join(v, "research", "other"), { recursive: true }); + writeFileSync(join(v, "research", "other", "dup.md"), "# Dup two\n"); + writeFileSync(join(v, "personal", "secret.md"), "# Private title\n\nPrivate body text.\n"); + writeFileSync(join(w.entries.lab.root, "local.md"), "# Local note\n\nLocal body.\n"); + writeFileSync(join(w.base, "company", "brief.md"), "# Company brief\n\nCompany body.\n"); + return w; +} + +test("locator resolution: paths, note links, anchors, privacy and prose", () => { + const w = locatorWorld(); + const inv = w.inv(); + const r = new LocatorResolver(inv); + const lab = w.entries.lab; + const at = (loc: string, anchor: string | null = null, entry = lab, res = r) => res.resolve(entry, loc, anchor); + + assert.deepEqual(at("https://example.invalid/x"), { kind: "url", status: "external" }); + assert.deepEqual(at("git:abc123:src/x.ts"), { kind: "git", status: "external" }); + assert.deepEqual(at("owner message in a chat on 2026-10-20"), { kind: "text", status: "not-checked" }); + assert.deepEqual(at("ssh host 'df -h /'"), { kind: "text", status: "not-checked" }); + + const local = at("local.md"); + assert.equal(local.status, "resolved"); + assert.equal(local.title, "Local note"); + assert.equal(local.excerpt, "Local body."); + + const fromRepo = at("research/notes/Đakovo trip.md", "budget"); + assert.equal(fromRepo.status, "resolved"); + assert.equal(fromRepo.title, "Trip to Đakovo"); + assert.equal(fromRepo.anchorFound, true); + assert.equal(fromRepo.excerpt, "Costs are low."); + assert.equal(at("research/notes/Đakovo trip.md#Not a heading").anchorFound, false); + assert.equal(at("research/notes/Đakovo trip.md:12").status, "resolved"); + + const link = at("[[Dakovo trip#Budget and costs|costs]]"); + assert.equal(link.kind, "wikilink"); + assert.equal(link.status, "resolved", "a folded name finds a note with diacritics"); + assert.equal(link.anchorFound, true); + const amb = at("[[dup]]"); + assert.equal(amb.status, "ambiguous"); + assert.equal(amb.candidates?.length, 2); + assert.equal(at("[[No such note]]").status, "missing"); + assert.equal(at("research/notes/missing.md").status, "missing"); + + const priv = at("personal/secret.md"); + assert.equal(priv.status, "resolved"); + assert.equal(priv.private, true); + assert.equal(priv.title, "Private title"); + assert.equal(priv.excerpt, undefined, "a private root returns path and title only"); + const full = at("personal/secret.md", null, lab, new LocatorResolver(inv, { includePrivate: true })); + assert.equal(full.excerpt, "Private body text."); + + // The company scope is not a root, but its own notes resolve for its own citations, with detail. + const co = at("brief.md", null, w.entries.co); + assert.equal(co.status, "resolved"); + assert.equal(co.excerpt, "Company body."); + // From another scope, a file outside every root resolves by explicit path, path and title only. + const outside = at(join(w.base, "company", "brief.md")); + assert.equal(outside.status, "resolved"); + assert.equal(outside.excerpt, undefined); +}); + +test("locators route: per-row resolution, counts, plan filter, and include-private is recorded in the usage log", (t) => { + const w = locatorWorld(); + const before = process.env.MOZAK_USAGE_LOG; + process.env.MOZAK_USAGE_LOG = "on"; + t.after(() => { if (before === undefined) delete process.env.MOZAK_USAGE_LOG; else process.env.MOZAK_USAGE_LOG = before; }); + w.propose("lab", "p1", { title: "Lab trip budget", sources: [{ locator: "local.md" }, { locator: "https://example.invalid" }, { locator: "personal/secret.md" }] }); + w.propose("me", "p2", { title: "Personal errand list", sources: [{ locator: "secret.md" }] }); + const one = w.op("locators", { scope: "lab" }); + assert.equal(one.exitCode, 0); + assert.deepEqual(one.data.counts, { resolved: 2, external: 1 }); + const rows = one.data.locators as { planId: string; locator: string; excerpt?: string; private?: boolean }[]; + assert.equal(rows.find((x) => x.locator === "personal/secret.md")?.excerpt, undefined); + const all = w.op("locators", { all: true, plan: "p2", includePrivate: true }); + assert.equal(all.exitCode, 0); + assert.equal((all.data.locators as { excerpt?: string }[])[0].excerpt, "Private body text."); + assert.equal(w.op("locators", { all: true, plan: "nope" }).data.status, "plan-not-found"); + assert.equal(w.op("locators", { scope: "lab", all: true }).exitCode, 2); + const month = new Date().toISOString().slice(0, 7); + const lines = readUsageLines(w.base, month).filter((l) => l.op === "locators"); + assert.deepEqual(lines.map((l) => l.includePrivate === true), [false, true, false, false]); +}); + +test("cited-note staleness: check reports a cited note changed after its citation landed, as information only", () => { + const w = s6world({ lab: "vault/research/lab" }, { repos: ["vault"] }); + const v = join(w.base, "vault"); + mkdirSync(join(v, "research", "notes"), { recursive: true }); + for (const n of ["topic", "early", "between", "dirty"]) writeFileSync(join(v, "research", "notes", `${n}.md`), `# ${n}\n\nfirst\n`); + writeFileSync(join(v, ".gitignore"), ".mozak-cache/\n"); + git(v, ["add", "-A"]); + git(v, ["commit", "-qm", "base"], "2026-01-01T00:00:00Z"); + w.propose("lab", "p", { title: "Lab topic survey" }); + for (const n of ["topic", "early", "between", "dirty"]) w.observe("lab", "p", `research/notes/${n}.md`, "2026-02-01T00:00:00.000Z"); + writeFileSync(join(v, "research", "notes", "between.md"), "# between\n\nedited before the citation was committed\n"); + git(v, ["add", "research/notes/between.md"]); + git(v, ["commit", "-qm", "between"], "2026-02-01T00:05:00Z"); + git(v, ["add", "-A"]); + git(v, ["commit", "-qm", "citation lands"], "2026-02-01T00:10:00Z"); + writeFileSync(join(v, "research", "notes", "topic.md"), "# topic\n\nedited later\n"); + git(v, ["add", "research/notes/topic.md"]); + git(v, ["commit", "-qm", "later edit"], "2026-03-01T00:00:00Z"); + writeFileSync(join(v, "research", "notes", "dirty.md"), "# dirty\n\nuncommitted edit\n"); + + const check = w.op("check", { scope: "lab" }); + const cited = (check.data.issues as Issue[]).filter((i) => i.code === "cited-note-changed"); + assert.deepEqual(cited.map((i) => [i.path!.split("/").pop(), i.source]), [["dirty.md", "uncommitted"], ["topic.md", "commit"]]); + assert.match(cited[1].message, /plan p cites research\/notes\/topic\.md, which changed 2026-03-01 after it was cited 2026-02-01/); + assert.equal(check.exitCode, 0, "cited-note changes are information, not findings"); + assert.equal(check.data.status, "ok"); +}); + +test("plans.md: one file per repo, titles and states only, company plans only in the company file, rejected left out", () => { + const w = s6world({ me: "vault/personal/me", lab: "vault/research/lab", co: "company", loose: "loose/x" }, { repos: ["vault", "company"] }); + w.propose("me", "errand", { title: "Personal errand list", purpose: "SECRET-PURPOSE-TEXT" }); + w.propose("me", "dropped", { title: "Dropped idea" }, "reject"); + w.propose("lab", "survey", { title: "Lab survey" }, "await"); + w.propose("co", "pilot", { title: "Company pilot", purpose: "COMPANY-PURPOSE-TEXT" }); + + const printed = w.op("plans-md", { print: true }); + assert.equal(printed.exitCode, 0); + const files = printed.data.files as { path: string; content: string; result: string; plans: number }[]; + assert.deepEqual(files.map((f) => [f.path.split("/").slice(-2).join("/"), f.result, f.plans]), [["company/plans.md", "printed", 1], ["vault/plans.md", "printed", 2]]); + assert.deepEqual(printed.data.skipped, [{ scope: "loose", reason: "not-in-git-repo" }]); + const [company, vault] = files.map((f) => f.content); + assert.ok(company.startsWith(PLANS_INDEX_MARKER)); + assert.ok(company.includes("- open: Company pilot (`pilot`)")); + assert.ok(!company.includes("errand") && !company.includes("Lab survey")); + assert.ok(vault.includes("- open: Personal errand list (`errand`)")); + assert.ok(vault.includes("- awaiting approval: Lab survey (`survey`)")); + assert.ok(vault.includes("Scope `me`, folder `personal/me`.")); + for (const text of [company, vault]) { + assert.ok(!text.includes("PURPOSE-TEXT"), "no purposes"); + assert.ok(!text.includes("Dropped idea"), "rejected drafts are left out"); + } + assert.ok(!existsSync(join(w.base, "vault", "plans.md")), "print writes nothing"); + + assert.equal(w.op("plans-md", {}).data.status, "not-permitted"); + const wrote = w.op("plans-md", {}, "owner"); + assert.equal(wrote.exitCode, 0); + assert.deepEqual((wrote.data.files as { result: string }[]).map((f) => f.result), ["written", "written"]); + assert.equal(readFileSync(join(w.base, "vault", "plans.md"), "utf8"), vault); + assert.deepEqual((w.op("plans-md", {}, "owner").data.files as { result: string }[]).map((f) => f.result), ["unchanged", "unchanged"]); + assert.deepEqual(readdirSync(join(w.base, "vault")).filter((n) => n.includes(".tmp")), []); + + writeFileSync(join(w.base, "company", "plans.md"), "# My own plans file\n"); + const conflict = w.op("plans-md", {}, "owner"); + assert.equal(conflict.exitCode, 3); + assert.equal((conflict.data.issues as Issue[])[0].code, "plans-md-conflict"); + assert.equal(readFileSync(join(w.base, "company", "plans.md"), "utf8"), "# My own plans file\n"); +}); + +test("note title and anchored section helpers", () => { + assert.equal(noteTitle("---\ntitle: From front matter\n---\nbody"), "From front matter"); + assert.equal(noteTitle("no heading"), null); + assert.equal(anchoredSection("# A\n\n## Rok prijave\n\nDo 1. 11. 2026.\n## Next\n", "rok"), "\nDo 1. 11. 2026."); +}); diff --git a/packages/core/test/scope-process.test.ts b/packages/core/test/scope-process.test.ts index 68a71ce..d803e51 100644 --- a/packages/core/test/scope-process.test.ts +++ b/packages/core/test/scope-process.test.ts @@ -5,6 +5,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, u import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { inspectLock, recoverLock } from "../src/lock-recover.ts"; // Process-level acceptance for A11 to A15. Every writer is a real child process running the real // scope-store. The parent never imports store logic: it reads and writes state only through child @@ -71,10 +72,13 @@ function world(name: string): { entry: Scope; initRequest: Record(); function jobFile(root: string, name: string, job: Record): string { const dir = scratchJobs(root); const path = join(dir, `${name}-${randomSuffix()}.json`); - writeFileSync(path, JSON.stringify(job)); + writeFileSync(path, JSON.stringify(rebaseRoots.has(root) ? { ...job, rebase: true } : job)); return path; } @@ -667,3 +671,156 @@ for (const { phase, state, temps: expectedTemps } of CRASH_POINTS) { assert.deepEqual(readdirSync(entry.root).filter((n) => n.endsWith(".tmp")), [], "leftover temp files removed"); }); } + +// ---------- V-race (S1b read-set rebase). Synthetic scopes, real child processes. ---------- + +const pause = (ms: number) => new Promise((r) => setTimeout(r, ms)); + +async function raceWorld(name: string, rebase: boolean, outcomes: string[], extraPlans: string[] = []): Promise { + const { entry } = await initialized(name); + if (rebase) rebaseRoots.add(entry.root); + const setup = await runChild({ mode: "setup", root: entry.root, scopeId: entry.id, setup: { planId: "demo", outcomes, extraPlans } }, { jobName: "setup" }); + assert.equal(setup.ok, true, `setup failed: ${setup.code} ${setup.message}`); + return entry; +} + +function percentile(values: number[], p: number): number { + if (!values.length) return 0; + const sorted = [...values].sort((a, b) => a - b); + return sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)]!; +} + +test("V-race 1: A0 replay, 3 agents on 3 outcomes of one plan: under 5% wasted attempts with rebase on, 0 lost writes either way", async () => { + const perAgent = Number(process.env.MOZAK_VRACE_A0_COUNT ?? 10); + const summary: Record = {}; + for (const rebase of [false, true]) { + const entry = await raceWorld(`a0-${rebase ? "on" : "off"}`, rebase, ["o1", "o2", "o3"]); + const tags = ["ra", "rb", "rc"]; + const results = await Promise.all(tags.map((tag, k) => runChild({ + mode: "race", root: entry.root, scopeId: entry.id, lockTimeoutMs: 5000, + race: { planId: "demo", outcomeId: `o${k + 1}`, tag, count: perAgent, attempts: 500, thinkMinMs: 20, thinkMaxMs: 50, seed: 11 + k }, + }, { jobName: `race-${tag}` }))); + let commits = 0, attempts = 0, rebased = 0; + const latencies: number[] = []; + for (const r of results) { + assert.equal(r.ok, true, `agent failed: ${r.code} ${r.message}`); + console.log(`V-race 1 flag ${rebase ? "on" : "off"} agent: stale ${r.outcome.stale}, busy ${r.outcome.busy}, refusals ${JSON.stringify(r.outcome.refusals)}`); + assert.deepEqual(r.outcome.failed, []); + commits += r.outcome.commits; attempts += r.outcome.attempts; rebased += r.outcome.rebased; latencies.push(...r.outcome.latencies); + } + const read = await readViaChild(entry); + const present = new Set(read.outcome.observationIds); + const expected = tags.flatMap((tag) => Array.from({ length: perAgent }, (_, i) => `${tag}-${i}`)); + const lost = expected.filter((id) => !present.has(id)).length; + summary[rebase ? "on" : "off"] = { commits, attempts, wasted: attempts - commits, lost, rebased, p95: percentile(latencies, 95) }; + assert.equal(commits, tags.length * perAgent); + assert.equal(lost, 0, "no committed observation is lost"); + assert.equal(read.outcome.projectionStatus, "current"); + } + const fmt = (k: string) => { const s = summary[k]!; return `flag ${k}: ${s.wasted} of ${s.attempts} attempts wasted (${((100 * s.wasted) / s.attempts).toFixed(1)}%), commits ${s.commits}, rebased ${s.rebased}, lost ${s.lost}, commit p95 ${s.p95} ms`; }; + console.log(`V-race 1 (3 agents x ${perAgent}, think 20-50 ms): ${fmt("off")}; ${fmt("on")}`); + assert.ok(summary.on!.wasted / summary.on!.attempts < 0.05, "rebase keeps wasted attempts under 5%"); +}); + +test("V-race 9: 8 writers with kill -9 and rebase on: commit p95 under 300 ms and 0 violations", async () => { + const target = Number(process.env.MOZAK_VRACE_KILL_OPS ?? 60); + // Agents think between writes; real LLM turns are 5-60 s. One commit costs about 45 ms here (six fsyncs), so + // 8 writers with no think time queue on the lock for more than 300 ms by arithmetic alone. + const [THINK_MIN, THINK_MAX] = (process.env.MOZAK_VRACE_THINK ?? "1000-2000").split("-").map(Number) as [number, number]; + const writers = 8; + const entry = await raceWorld("kill9", true, Array.from({ length: writers }, (_, k) => `o${k + 1}`), Array.from({ length: writers }, (_, k) => `d${k + 1}`)); + const jobs = scratchJobs(entry.root); + let attempts = 0, commits = 0, stale = 0, busy = 0, rebasedTotal = 0, kills = 0, holderKills = 0, locksLeft = 0, locksRecovered = 0, renders = 0, round = 0; + const violations: string[] = []; + const latencies: number[] = []; + let seed = 100; + while (attempts < target) { + round++; + const ackFiles = Array.from({ length: writers }, (_, k) => join(jobs, `ack-r${round}-w${k + 1}.tsv`)); + for (const f of ackFiles) writeFileSync(f, ""); + const running = Array.from({ length: writers }, (_, k) => { + const job = { mode: "race", root: entry.root, scopeId: entry.id, lockTimeoutMs: 2000, race: { + planId: "demo", outcomeId: `o${k + 1}`, tag: `r${round}w${k + 1}`, count: 100000, attempts: 50, thinkMinMs: THINK_MIN, thinkMaxMs: THINK_MAX, seed: seed++, + ackFile: ackFiles[k], deadlineMs: 4000, discussionPlanId: `d${k + 1}`, discussionRate: 0.15, proposeRate: 0.1, supersedeRate: 0.2, + } }; + const path = jobFile(entry.root, `kill-r${round}-w${k + 1}`, job); + const child = spawn(process.execPath, ["--experimental-strip-types", childPath, path], { stdio: ["ignore", "pipe", "pipe", "ipc"] }); + liveChildren.add(child); + let stdout = ""; + child.stdout!.on("data", (d) => (stdout += d)); + const done = new Promise((res) => child.once("exit", (code, signal) => { + liveChildren.delete(child); + if (signal) return res({ ok: false, code: `signal-${signal}`, exitCode: -1 }); + try { res({ ...JSON.parse(stdout.trim().split("\n").pop()!), exitCode: code ?? -1 }); } catch { res({ ok: false, code: "no-output", exitCode: code ?? -1 }); } + })); + return { child, done }; + }); + await pause(400 + Math.floor(Math.random() * 1600)); + // Odd rounds kill whichever writer holds the scope lock (mid-write crash), even rounds a random writer. + let victim = running[Math.floor(Math.random() * writers)]!; + if (round % 2 === 1) { + const until = Date.now() + 3000; + let holder: (typeof running)[number] | undefined; + while (!holder && Date.now() < until) { + try { const pid = JSON.parse(readFileSync(join(lockPath(entry.root), "owner.json"), "utf8")).pid; holder = running.find((r) => r.child.pid === pid); } catch { /* no holder yet */ } + if (!holder) await pause(1); + } + if (holder) { victim = holder; holderKills++; } + } + victim.child.kill("SIGKILL"); kills++; + const results = await Promise.all(running.map((r) => r.done)); + // Recovery only after every writer of this round has been joined. S2: the owner route `recover` clears a lock whose + // pid on this host is dead; a lock killed before its owner.json was written still needs offline removal. + if (existsSync(lockPath(entry.root))) { + locksLeft++; + const lock = inspectLock(entry.root); + if (lock.verdict === "dead-local-pid") { + const recovered = recoverLock(entry, { requestId: `vrace9-r${round}`, scopeId: entry.id, lock: { token: lock.token!, host: lock.host!, pid: lock.pid! }, ownerRef: "synthetic:owner-recover", ownerMessageAt: "2026-10-21T00:00:00.000Z" }); + if (recovered.status !== "ok") violations.push(`round ${round}: recover ${recovered.status}`); + locksRecovered++; + } else { + if (lock.verdict === "live-local-pid" || lock.verdict === "other-host") violations.push(`round ${round}: lock left with verdict ${lock.verdict}`); + rmSync(lockPath(entry.root), { recursive: true, force: true }); + } + } + for (const r of results) { + if (r.code === "signal-SIGKILL") continue; + if (!r.ok) { violations.push(`round ${round}: writer error ${r.code} ${r.message}`); continue; } + if (r.outcome.failed.length) violations.push(`round ${round}: ${r.outcome.failed.join(",")}`); + attempts += r.outcome.attempts; commits += r.outcome.commits; stale += r.outcome.stale; busy += r.outcome.busy; rebasedTotal += r.outcome.rebased; + latencies.push(...r.outcome.latencies); + } + let read = await readViaChild(entry); + if (read.outcome.projectionStatus !== "current") { + const rendered = await runChild({ mode: "render", root: entry.root, scopeId: entry.id }, { jobName: "render" }); + if (!rendered.ok || rendered.outcome.result !== "rendered") violations.push(`round ${round}: render ${rendered.code ?? rendered.outcome?.result}`); + renders++; + read = await readViaChild(entry); + } + if (read.outcome.projectionStatus !== "current") violations.push(`round ${round}: projection ${read.outcome.projectionStatus}`); + const observations = new Set(read.outcome.observationIds); + const plans = new Set((read.outcome as any).planIds as string[]); + const receipts = new Set((read.outcome as any).receiptOperationIds as string[]); + const discussions = (read.outcome as any).discussions as Record; + for (const [k, file] of ackFiles.entries()) { + const acks = readFileSync(file, "utf8").split("\n").filter(Boolean).map((line) => line.split("\t") as [string, string, string]); + for (const [opId, kind, id] of acks) { + if (!receipts.has(opId)) violations.push(`round ${round}: acked ${opId} has no receipt`); + if (kind === "observe" && !observations.has(id)) violations.push(`round ${round}: acked observation ${id} lost`); + if (kind === "propose" && !plans.has(id)) violations.push(`round ${round}: acked plan ${id} lost`); + } + const lastDiscussion = acks.filter((a) => a[1] === "save-discussion").pop(); + if (lastDiscussion) { + const current = discussions[`d${k + 1}`] ?? ""; + const index = (s: string) => Number(s.split("-").pop()); + if (!current.startsWith(`summary r${round}w${k + 1}-`) || index(current) < index(lastDiscussion[0])) violations.push(`round ${round}: discussion d${k + 1} lost ${lastDiscussion[0]} (now ${current})`); + } + } + const checked = await runChild({ mode: "check", root: entry.root, scopeId: entry.id }, { jobName: "kill-check" }); + if (!checked.ok || checked.outcome.status !== "ok") violations.push(`round ${round}: check ${checked.code ?? checked.outcome.status} ${JSON.stringify(checked.outcome?.issues ?? [])}`); + } + const p95 = percentile(latencies, 95); + console.log(`V-race 9 (8 writers, think ${THINK_MIN}-${THINK_MAX} ms, rebase on): rounds ${round}, kill -9 ${kills} (${holderKills} while holding the lock), write attempts ${attempts} by joined writers, commits ${commits}, stale ${stale}, busy ${busy}, rebased ${rebasedTotal}, locks left by killed writers ${locksLeft} (${locksRecovered} cleared by recover), renders ${renders}, commit p50 ${percentile(latencies, 50)} ms, p95 ${p95} ms, max ${percentile(latencies, 100)} ms, violations ${violations.length}`); + assert.deepEqual(violations, []); + assert.ok(p95 < 300, `commit p95 ${p95} ms`); +}); diff --git a/packages/core/test/scope-writer-child.ts b/packages/core/test/scope-writer-child.ts index 2bb7719..b57cc23 100644 --- a/packages/core/test/scope-writer-child.ts +++ b/packages/core/test/scope-writer-child.ts @@ -9,23 +9,36 @@ // pauseMs: finite block duration in ms, or null/absent to block until the parent SIGKILLs us // lockTimeoutMs: passed to the store seam // append: { planId, tag, count, attempts } for mode "append" (three-writer test) +// race: RaceJob for mode "race" (V-race replay and kill -9 writers); setup: SetupJob for mode "setup" // // Pausing happens once per process. Readers hit "reader-between" on every attempt, so the pause is // only taken the first time to avoid an unbounded loop in the test. -import { readFileSync } from "node:fs"; -import { initScopeState, mutateScope, readScope, repairProjection, type StoreOptions } from "../src/scope-store.ts"; +import { appendFileSync, readFileSync } from "node:fs"; +import { initScopeState, mutateScope, readScope, renderProjection, repairProjection, type StoreOptions } from "../src/scope-store.ts"; +import { reviewShow } from "../src/review.ts"; import { executeOperation } from "../src/api.ts"; interface AppendJob { planId: string; tag: string; count: number; attempts: number } +interface RaceJob { + planId: string; outcomeId: string; tag: string; count: number; attempts: number; + thinkMinMs: number; thinkMaxMs: number; seed: number; + ackFile?: string; deadlineMs?: number; + // Mixed workload for the kill -9 run: share of save-discussion on discussionPlanId, propose, and supersede. + discussionPlanId?: string; discussionRate?: number; proposeRate?: number; supersedeRate?: number; +} +interface SetupJob { planId: string; outcomes: string[]; extraPlans?: string[] } interface Job { - mode: "init" | "mutate" | "repair" | "read" | "append" | "check"; + mode: "init" | "mutate" | "repair" | "read" | "append" | "check" | "race" | "setup" | "render"; root: string; scopeId: string; request?: unknown; pauseAt?: string; pauseMs?: number | null; lockTimeoutMs?: number; + rebase?: boolean; append?: AppendJob; + race?: RaceJob; + setup?: SetupJob; } const jobPath = process.argv[2]; @@ -49,6 +62,7 @@ function announceAndBlock(phase: string): void { const options: StoreOptions = { lockTimeoutMs: job.lockTimeoutMs, + rebase: job.rebase === true, onPhase(phase: string) { if (!paused && job.pauseAt === phase) { paused = true; @@ -101,6 +115,92 @@ function runAppend(append: AppendJob): { committed: number; retries: number; fai return out; } +const pause = (ms: number) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }; +function random(seed: number): () => number { + let s = seed >>> 0; + return () => { s = (s + 0x6d2b79f5) >>> 0; let t = s; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; +} +const fixtureContent = (title: string, outcomes: string[]) => ({ + title, purpose: `Purpose ${title}`, constraints: [], nonGoals: [], rationale: "Synthetic fixture", questions: [], sources: [], + outcomes: outcomes.map(id => ({ id, statement: `Statement ${id}`, acceptance: "objective", criterion: `Check ${id}` })), +}); + +/** Propose and owner-approve a plan with the given outcomes, plus optional extra unaccepted plans. */ +function runSetup(setup: SetupJob): unknown { + let n = 0; + const write = (action: string, payload: unknown, actor: "agent" | "owner" = "agent") => + mutateScope(entry, { operationId: `setup-${++n}-${action}`, scopeId: entry.id, expected: readScope(entry).snapshot, action, payload }, actor, options); + write("propose", { planId: setup.planId, content: fixtureContent(`Race fixture ${setup.planId}`, setup.outcomes) }); + const shown = reviewShow(readScope(entry).state, setup.planId, "approve-direction"); + write("approve-direction", { planId: setup.planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: "synthetic-owner:race", ownerMessageAt: "2026-10-12T08:00:00.000Z", reason: "fixture approval" }, "owner"); + for (const id of setup.extraPlans ?? []) write("propose", { planId: id, content: fixtureContent(`Topic ${id}zq`, ["d1"]) }); + // Let the owner approval age past the rebase guard window, then leave one ordinary append as the latest write. + pause(1100); + write("observe", { planId: setup.planId, observation: { id: "warmup", classification: "unverified", summary: "fixture warm-up", evidence: [] }, reasoningLinks: [] }); + return { status: "ok", acceptedRevisionId: readScope(entry).state.plans.find(p => p.id === setup.planId)!.accepted!.id }; +} + +/** + * One agent: read, think, write, as in the A0 experiment. On stale-input or busy it rereads and retries. + * Every attempt is timed. A commit is acknowledged in ackFile (synchronous append) right after it returns. + */ +function runRace(job: RaceJob): unknown { + const r = random(job.seed); + const out = { commits: 0, attempts: 0, stale: 0, busy: 0, rebased: 0, failed: [] as string[], latencies: [] as number[], kinds: {} as Record, refusals: {} as Record }; + const mine: string[] = []; + const deadline = job.deadlineMs ? Date.now() + job.deadlineMs : Infinity; + for (let i = 0; i < job.count && Date.now() < deadline; i++) { + const pick = r(); + const kind = job.discussionPlanId && pick < (job.discussionRate ?? 0) ? "save-discussion" + : pick < (job.discussionRate ?? 0) + (job.proposeRate ?? 0) ? "propose" : "observe"; + const operationId = `${job.tag}-${i}`; + let done = false; + for (let attempt = 0; attempt < job.attempts && !done && Date.now() < deadline; attempt++) { + const read = readScope(entry); + pause(job.thinkMinMs + Math.floor(r() * (job.thinkMaxMs - job.thinkMinMs + 1))); + let payload: Record; + if (kind === "save-discussion") { + const plan = read.state.plans.find(p => p.id === job.discussionPlanId)!; + payload = { planId: plan.id, acceptedRevisionId: plan.accepted?.id ?? null, pendingRevisionId: plan.pending?.id ?? null, summary: `summary ${operationId}`, stage: "clarifying", questions: [] }; + } else if (kind === "propose") { + payload = { planId: `np${job.tag}x${i}`, content: fixtureContent(`Item ${job.tag}x${i}q`, ["z1"]) }; + } else { + const revisionId = read.state.plans.find(p => p.id === job.planId)!.accepted!.id; + const supersedes = mine.length && r() < (job.supersedeRate ?? 0) ? mine[Math.floor(r() * mine.length)] : undefined; + payload = { + planId: job.planId, + observation: { id: operationId, classification: "observed", summary: `check ${operationId}`, ...(supersedes ? { supersedesObservationId: supersedes } : {}), evidence: [{ id: `${operationId}-e`, locator: "test:race", anchor: null, version: null, inspectedAt: "2026-10-12T08:30:00.000Z", activity: { kind: "run", description: "synthetic run" }, result: { verdict: "pass", summary: "passed" }, limitations: [] }] }, + reasoningLinks: [{ id: `${operationId}-l`, relation: "supports", from: { planId: job.planId, revisionId: null, kind: "observation", id: operationId }, to: { planId: job.planId, revisionId, kind: "outcome", id: job.outcomeId }, rationale: "race support" }], + }; + } + out.attempts++; + const started = performance.now(); + try { + const result = mutateScope(entry, { operationId, scopeId: entry.id, expected: read.snapshot, action: kind, payload }, "agent", options); + out.latencies.push(Math.round((performance.now() - started) * 10) / 10); + if (mutationStatus(result.status)) { + done = true; out.commits++; out.kinds[kind] = (out.kinds[kind] ?? 0) + 1; + if (result.rebased) out.rebased++; + if (kind === "observe") mine.push(operationId); + if (job.ackFile) appendFileSync(job.ackFile, `${operationId}\t${kind}\t${kind === "propose" ? `np${job.tag}x${i}` : operationId}\n`); + } + } catch (err) { + const code = String((err as { code?: unknown }).code ?? "unknown"); + if (code === "stale-input") { + out.stale++; + const why = String((err as Error).message).replace(/"[^"]*"/g, "X"); + out.refusals[why] = (out.refusals[why] ?? 0) + 1; + continue; + } + if (code === "busy") { out.busy++; continue; } + out.failed.push(`${operationId}:${code}`); + break; + } + } + } + return out; +} + try { let outcome: unknown; if (job.mode === "init") { @@ -116,6 +216,8 @@ try { snapshot: read.snapshot, projectionStatus: read.projectionStatus, plans: read.state.plans.length, + planIds: read.state.plans.map((p) => p.id).sort(), + discussions: Object.fromEntries(read.state.plans.filter((p) => p.discussion).map((p) => [p.id, p.discussion!.summary])), observationIds: read.state.plans.flatMap((p) => p.observations.map((o) => o.id)).sort(), // Receipts are keyed by unique operation ID. Expose the IDs so the parent can count them. receiptOperationIds: Object.keys(read.state.receipts).sort(), @@ -123,6 +225,15 @@ try { } else if (job.mode === "append") { if (!job.append) throw new Error("append mode requires an append job"); outcome = runAppend(job.append); + } else if (job.mode === "race") { + if (!job.race) throw new Error("race mode requires a race job"); + outcome = runRace(job.race); + } else if (job.mode === "setup") { + if (!job.setup) throw new Error("setup mode requires a setup job"); + outcome = runSetup(job.setup); + } else if (job.mode === "render") { + const { result, outcome: out } = renderProjection(entry, options); + outcome = { status: out.status, result }; } else if (job.mode === "check") { // The real public check route, as `mozak check` runs it. const out = executeOperation({ format: "mozak.local/v3", scopes: [entry], digest: "" } as Parameters[0], "check", { scope: entry.id }, "agent"); diff --git a/packages/core/test/settings-rebase.test.ts b/packages/core/test/settings-rebase.test.ts new file mode 100644 index 0000000..ef124ab --- /dev/null +++ b/packages/core/test/settings-rebase.test.ts @@ -0,0 +1,93 @@ +// Gap 7: one mozak-settings.json per installation, next to the inventory. concurrency.rebase lives there, +// per scope under scopes..concurrency.rebase with a top-level default. Synthetic temp scopes only. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { world, cleanup } from "./annotations-fixture.ts"; +import { readScope } from "../src/scope-store.ts"; +import { loadSettings, rebaseEnabled, SETTINGS_FILE } from "../src/settings.ts"; +import { REBASE_GUARD_MS } from "../src/rebase.ts"; + +after(cleanup); +type Issue = { code: string; message: string }; +const FORMAT = "mozak.settings/v1"; +const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); + +test("settings: concurrency.rebase is read next to the inventory, per scope over the top-level default", () => { + const w = world(["alpha", "beta"]); + assert.equal(rebaseEnabled(w.inv(), "alpha"), false, "absent file keeps rebase off"); + const put = (value: unknown) => writeFileSync(join(w.base, SETTINGS_FILE), typeof value === "string" ? value : JSON.stringify(value)); + put({ format: FORMAT, concurrency: { rebase: true } }); + assert.equal(rebaseEnabled(w.inv(), "alpha"), true); + assert.equal(rebaseEnabled(w.inv(), "beta"), true); + put({ format: FORMAT, concurrency: { rebase: true }, scopes: { beta: { concurrency: { rebase: false } } } }); + assert.equal(rebaseEnabled(w.inv(), "alpha"), true); + assert.equal(rebaseEnabled(w.inv(), "beta"), false); + put({ format: FORMAT, scopes: { beta: { concurrency: { rebase: true } } } }); + assert.equal(rebaseEnabled(w.inv(), "alpha"), false); + assert.equal(rebaseEnabled(w.inv(), "beta"), true); + assert.deepEqual(loadSettings(w.inv()).scopes.beta, { concurrency: { rebase: true } }); + for (const bad of ["{", JSON.stringify({ format: FORMAT, concurrency: { rebase: "yes" } }), JSON.stringify({ format: FORMAT, concurrency: true }), + JSON.stringify({ format: FORMAT, scopes: { alpha: { concurrency: { rebase: 1 } } } }), JSON.stringify({ concurrency: { rebase: true } })]) { + put(bad); + assert.equal(rebaseEnabled(w.inv(), "alpha"), false, bad); + assert.throws(() => loadSettings(w.inv()), { code: "settings-invalid" }, bad); + } +}); + +test("settings: an invalid value is a check finding and an unknown concurrency key is settings-unknown-key", () => { + const w = world(["alpha"], { settings: { format: FORMAT, concurrency: { rebase: "yes" } } }); + let codes = (w.op("check", { scope: "alpha" }).data.issues as Issue[]).map(i => i.code); + assert.ok(codes.includes("settings-invalid"), codes.join(",")); + writeFileSync(join(w.base, SETTINGS_FILE), JSON.stringify({ format: FORMAT, concurrency: { rebase: false, typo: 1 }, scopes: { alpha: { concurrency: { other: 2 } } } })); + codes = (w.op("check", { scope: "alpha" }).data.issues as Issue[]).map(i => i.code); + assert.deepEqual(codes.filter(c => c.startsWith("settings")), ["settings-unknown-key", "settings-unknown-key"]); +}); + +function staleObserve(w: ReturnType) { + w.propose("alpha", "p1", { outcomes: [{ id: "o1" }, { id: "o2" }] }); + pause(REBASE_GUARD_MS + 100); // let init and the owner approval age past the rebase guard window + w.pass("alpha", "p1", "o1"); + const stale = readScope(w.entries.alpha).snapshot; + w.pass("alpha", "p1", "o1"); + const p = w.plan("alpha", "p1"); + const id = "late-obs"; + const evidence = { id: `${id}-e`, locator: "synthetic.ts", anchor: null, version: null, inspectedAt: "2026-10-20T09:00:00.000Z", activity: { kind: "run", description: "synthetic" }, result: { verdict: "pass", summary: "passed" }, limitations: [] }; + const payload = { planId: "p1", observation: { id, classification: "observed", summary: id, evidence: [evidence] }, reasoningLinks: [{ id: `${id}-link`, relation: "supports", from: { planId: "p1", revisionId: null, kind: "observation", id }, to: { planId: "p1", revisionId: p.accepted!.id, kind: "outcome", id: "o2" }, rationale: "synthetic" }] }; + return w.op("observe", { scope: "alpha", request: { operationId: "stale-observe", scopeId: "alpha", expected: stale, action: "observe", payload } }); +} + +test("settings: concurrency.rebase defaults off: no settings file, or a file without it, refuses a stale observe", () => { + for (const settings of [undefined, { format: FORMAT }, { format: FORMAT, scopes: { alpha: { annotations: true } } }]) { + const w = world(["alpha"], { settings }); + assert.equal(rebaseEnabled(w.inv(), "alpha"), false, JSON.stringify(settings)); + const refused = staleObserve(w); + assert.equal(refused.exitCode, 3, JSON.stringify(settings)); + assert.equal((refused.data as { status: string }).status, "stale-input"); + assert.equal((refused.data as { rebased?: unknown }).rebased, undefined); + } +}); + +test("settings: the write route rebases a stale observe only when the inventory-adjacent file turns it on", () => { + const on = world(["alpha"], { settings: { format: FORMAT, scopes: { alpha: { concurrency: { rebase: true } } } } }); + const rebased = staleObserve(on); + assert.equal(rebased.exitCode, 0, JSON.stringify(rebased.data)); + assert.ok((rebased.data as { rebased?: unknown }).rebased); + + const off = world(["alpha"], { settings: { format: FORMAT, concurrency: { rebase: true }, scopes: { alpha: { concurrency: { rebase: false } } } } }); + const refused = staleObserve(off); + assert.equal(refused.exitCode, 3); + assert.equal((refused.data as { status: string }).status, "stale-input"); +}); + +test("settings: a mozak-settings.json in the scope folder is ignored and check warns settings-scope-file-deprecated", () => { + const w = world(["alpha"]); + writeFileSync(join(w.entries.alpha.root, SETTINGS_FILE), JSON.stringify({ concurrency: { rebase: true } })); + const issues = w.op("check", { scope: "alpha" }).data.issues as Issue[]; + const warning = issues.find(i => i.code === "settings-scope-file-deprecated"); + assert.ok(warning, issues.map(i => i.code).join(",")); + assert.match(warning!.message, /scopes\.alpha\.concurrency/); + assert.equal(rebaseEnabled(w.inv(), "alpha"), false); + assert.equal(staleObserve(w).exitCode, 3); +}); diff --git a/packages/core/test/stale.test.ts b/packages/core/test/stale.test.ts deleted file mode 100644 index bd9d89d..0000000 --- a/packages/core/test/stale.test.ts +++ /dev/null @@ -1,146 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { execFileSync } from "node:child_process"; -import { mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { renderStale, staleReports, touched } from "../src/index.ts"; - -const D = (iso: string) => Math.floor(Date.parse(iso + "T12:00:00Z") / 1000); - -function repo(): string { - const dir = mkdtempSync(join(tmpdir(), "mozak-s-")); - execFileSync("git", ["init", "-q", "-b", "main", dir]); - execFileSync("git", ["-C", dir, "config", "user.email", "t@t"]); - execFileSync("git", ["-C", dir, "config", "user.name", "t"]); - return dir; -} - -/** Write files then commit them with a fixed date, so assertions can be exact. */ -function commit(dir: string, files: Record, date: string) { - for (const [rel, text] of Object.entries(files)) { - const p = join(dir, rel); - mkdirSync(join(p, ".."), { recursive: true }); - writeFileSync(p, text); - } - const when = `${date}T12:00:00Z`; - execFileSync("git", ["-C", dir, "add", "-A"]); - execFileSync("git", ["-C", dir, "commit", "-q", "-m", "c", "--date", when], { env: { ...process.env, GIT_COMMITTER_DATE: when } }); -} - -const moz = (id: string, kind: string, links = "", plan = "- [ ] x") => - `---\nid: ${id}\nkind: ${kind}\nformat: 1\n---\n\n## Plan\n\n${plan}\n\n## Links\n\n${links}\n\n## Translations\n`; -const scopeFiles = (id: string, kind: string, links = "") => ({ - [`${id}/README.md`]: `# ${id}\n`, - [`${id}/AGENTS.md`]: `# ${id}\n`, - [`${id}/mozak.md`]: moz(id, kind, links), -}); - -test("touched reads the commit date of a file and of a directory", () => { - const r = repo(); - commit(r, { "a/one.md": "1\n", "b/two.md": "2\n" }, "2026-01-10"); - commit(r, { "a/one.md": "1b\n" }, "2026-03-05"); - assert.deepEqual(touched(join(r, "a")), { epoch: D("2026-03-05"), source: "commit" }); - assert.deepEqual(touched(join(r, "b/two.md")), { epoch: D("2026-01-10"), source: "commit" }); -}); - -test("uncommitted edits count as newer than the last commit", () => { - const r = repo(); - commit(r, { "a/one.md": "1\n" }, "2026-01-10"); - writeFileSync(join(r, "a/one.md"), "edited\n"); - const t = touched(join(r, "a")); - assert.equal(t.source, "uncommitted"); - assert.ok(t.epoch! > D("2026-01-10")); -}); - -test("a file with no git history is unknown, not fresh", () => { - const dir = mkdtempSync(join(tmpdir(), "mozak-nogit-")); - writeFileSync(join(dir, "x.md"), "x\n"); - assert.deepEqual(touched(join(dir, "x.md")), { epoch: null, source: "none" }); -}); - -test("a scope is flagged when something it depends on changed after it", () => { - const r = repo(); - commit(r, { ...scopeFiles("api", "project", "- depends-on: [[research]]"), ...scopeFiles("research", "topic") }, "2026-01-10"); - commit(r, { "research/notes.md": "new finding\n" }, "2026-02-20"); - const [api, research] = staleReports({ roots: [r] }, undefined, { now: D("2026-03-01") }); - assert.equal(api.id, "api"); - assert.equal(api.verdict, "inputs-changed"); - assert.equal(api.upstream[0].id, "research"); - assert.equal(api.upstream[0].newerBy, D("2026-02-20") - D("2026-01-10")); - assert.equal(research.verdict, "no-input-changed"); - assert.equal(api.daysSinceTouched, 50); -}); - -test("informs points the other way: the scope that informs me is my upstream", () => { - const r = repo(); - commit(r, { ...scopeFiles("research", "topic", "- informs: [[api]]"), ...scopeFiles("api", "project") }, "2026-01-10"); - commit(r, { "research/n.md": "x\n" }, "2026-02-01"); - const api = staleReports({ roots: [r] }, "api", { now: D("2026-03-01") })[0]; - assert.equal(api.verdict, "inputs-changed"); - assert.equal(api.upstream[0].direction, "reverse"); - const research = staleReports({ roots: [r] }, "research", { now: D("2026-03-01") })[0]; - assert.equal(research.verdict, "no-input-changed", "informing someone does not make me stale"); -}); - -test("when I am newer than everything I rely on, nothing is flagged", () => { - const r = repo(); - commit(r, scopeFiles("research", "topic"), "2026-01-10"); - commit(r, scopeFiles("api", "project", "- depends-on: [[research]]"), "2026-02-10"); - const api = staleReports({ roots: [r] }, "api", { now: D("2026-03-01") })[0]; - assert.equal(api.verdict, "no-input-changed"); -}); - -test("a note my files cite is flagged when it changed after me, and an unrelated note is not", () => { - const r = repo(); - commit(r, { "notes/Source A.md": "a\n", "notes/Source B.md": "b\n", "topic/README.md": "uses [[Source A]]\n", "topic/AGENTS.md": "x\n", "topic/mozak.md": moz("topic", "topic") }, "2026-01-10"); - commit(r, { "notes/Source A.md": "a2\n", "notes/Source B.md": "b2\n" }, "2026-02-15"); - const t = staleReports({ roots: [r] }, "topic", { now: D("2026-03-01") })[0]; - assert.deepEqual(t.notes.map((n) => n.name), ["Source A"], "only the cited note, not Source B"); - assert.equal(t.verdict, "inputs-changed"); - assert.match(renderStale([t]), /note \[\[Source A\]\] changed 2026-02-15 \+36d/); -}); - -test("a link that does not resolve here is reported as not judgeable instead of passing silently", () => { - const r = repo(); - commit(r, scopeFiles("api", "project", "- depends-on: [[elsewhere]]"), "2026-01-10"); - const api = staleReports({ roots: [r] }, "api", { now: D("2026-03-01") })[0]; - assert.deepEqual(api.unresolved, ["depends-on: [[elsewhere]]"]); - assert.match(renderStale([api]), /cannot judge, not found on this machine: depends-on: \[\[elsewhere\]\]/); -}); - -test("scopes across two different git repos are compared by their own commit dates", () => { - const vault = repo(); - const code = repo(); - commit(vault, scopeFiles("research", "topic"), "2026-01-10"); - commit(vault, { "research/n.md": "x\n" }, "2026-02-20"); - commit(code, scopeFiles("api", "project", "- depends-on: [[research]]"), "2026-02-01"); - const api = staleReports({ roots: [vault, code] }, "api", { now: D("2026-03-01") })[0]; - assert.equal(api.verdict, "inputs-changed"); - assert.equal(api.upstream[0].newerBy, D("2026-02-20") - D("2026-02-01")); -}); - -test("planOnly ignores edits to other files in a scope and only compares mozak.md", () => { - const r = repo(); - commit(r, { ...scopeFiles("api", "project", "- depends-on: [[lib]]"), ...scopeFiles("lib", "project") }, "2026-01-10"); - commit(r, { "lib/src/code.ts": "x\n" }, "2026-02-20"); - assert.equal(staleReports({ roots: [r] }, "api", { now: D("2026-03-01") })[0].verdict, "inputs-changed"); - assert.equal(staleReports({ roots: [r] }, "api", { now: D("2026-03-01"), planOnly: true })[0].verdict, "no-input-changed"); -}); - -test("the report is read only and leaves the files untouched", () => { - const r = repo(); - commit(r, scopeFiles("api", "project"), "2026-01-10"); - const before = execFileSync("git", ["-C", r, "status", "--porcelain"], { encoding: "utf8" }); - staleReports({ roots: [r] }); - assert.equal(execFileSync("git", ["-C", r, "status", "--porcelain"], { encoding: "utf8" }), before); -}); - -test("an untracked file in a dirty tree does not crash and uses its mtime", () => { - const r = repo(); - commit(r, scopeFiles("api", "project"), "2026-01-10"); - writeFileSync(join(r, "api/new.md"), "fresh\n"); - const old = new Date("2026-02-01T00:00:00Z"); - utimesSync(join(r, "api/new.md"), old, old); - assert.equal(touched(join(r, "api")).source, "uncommitted"); -}); diff --git a/packages/core/test/storage-hygiene.test.ts b/packages/core/test/storage-hygiene.test.ts index 585d749..761beba 100644 --- a/packages/core/test/storage-hygiene.test.ts +++ b/packages/core/test/storage-hygiene.test.ts @@ -49,7 +49,7 @@ for (const nested of [false, true]) { test("P0.5: init writes exactly the ignore lines when there is no .gitignore", () => { const { root, entry, request } = world(); initScopeState(entry, request); - assert.equal(readFileSync(join(root, ".gitignore"), "utf8"), ".mozak-write-lock/\nmozak.json.*.tmp\nmozak.md.*.tmp\nMOZAK.json.*.tmp\nMOZAK.md.*.tmp\n"); + assert.equal(readFileSync(join(root, ".gitignore"), "utf8"), ".mozak-write-lock/\nmozak.json.*.tmp\nmozak.md.*.tmp\nMOZAK.json.*.tmp\nMOZAK.md.*.tmp\nmozak.annotations.json.*.tmp\n"); }); test("P0.5: init refuses a .gitignore that is not a regular file", () => { diff --git a/packages/core/test/translate.test.ts b/packages/core/test/translate.test.ts deleted file mode 100644 index 17d4a83..0000000 --- a/packages/core/test/translate.test.ts +++ /dev/null @@ -1,67 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { mkdirSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { buildPacket, insertTranslation, parseMozak, renderTranslation, setAssumption } from "../src/index.ts"; -import { updateFile } from "../src/write.ts"; - -const base = `---\nid: target\nkind: project\nformat: 1\n---\n## Plan\n- [ ] x\n## Links\n## Translations\n`; -const draft = { title: "publishing concept", source: "src", target: "target", assumptions: ["deploys from main", "markdown build step"] }; - -test("a fresh translation is invalid until every assumption is re-derived", () => { - const text = insertTranslation(base, renderTranslation(draft), draft.title); - assert.equal(parseMozak(text).issues.filter((i) => i.code === "translation-open-assumption").length, 2); - - const one = setAssumption(text, draft.title, 1, "re-derived"); - assert.equal(parseMozak(one).issues.filter((i) => i.code === "translation-open-assumption").length, 1); - - const both = setAssumption(one, draft.title, 2, "re-derived"); - assert.deepEqual(parseMozak(both).issues, []); - assert.equal(parseMozak(both).translations[0].assumptions.every((a) => a.status === "re-derived"), true); -}); - -test("a translation needs assumptions and a title", () => { - assert.throws(() => renderTranslation({ ...draft, assumptions: [] }), /at least one assumption/); - assert.throws(() => renderTranslation({ ...draft, title: " " }), /needs a title/); -}); - -test("duplicate titles and missing sections are refused", () => { - const text = insertTranslation(base, renderTranslation(draft), draft.title); - assert.throws(() => insertTranslation(text, renderTranslation(draft), draft.title), /already exists/); - assert.throws(() => insertTranslation("no sections here", "x", "t"), /no "## Translations"/); -}); - -test("setAssumption only touches the named translation and reports bad numbers", () => { - let text = insertTranslation(base, renderTranslation(draft), draft.title); - text = insertTranslation(text, renderTranslation({ ...draft, title: "other idea" }), "other idea"); - const out = setAssumption(text, "other idea", 1, "re-derived"); - const doc = parseMozak(out); - assert.equal(doc.translations[0].assumptions[0].status, "open"); - assert.equal(doc.translations[1].assumptions[0].status, "re-derived"); - assert.throws(() => setAssumption(text, draft.title, 9, "re-derived"), /no number 9/); - assert.throws(() => setAssumption(text, "nope", 1, "re-derived"), /no translation titled/); -}); - -test("packet carries both plans, the existing relation, and the draft", () => { - const source = parseMozak(`---\nid: src\nkind: topic\nformat: 1\n---\n## Plan\nsource plan\n## Links\n- informs: [[target]]\n## Translations\n`); - const target = parseMozak(base); - const p = buildPacket(source, target, draft); - assert.deepEqual(p.related, ["src informs target"]); - assert.equal(p.source.plan, "source plan"); - assert.match(p.draft, /\[open\] deploys from main/); - assert.ok(p.instructions.some((i) => /Do not carry the source's answer over/.test(i))); -}); - -test("legacy translation writer is disabled without changing existing Markdown", () => { - const dir = mkdtempSync(join(tmpdir(), "mozak-t-")); - mkdirSync(dir, { recursive: true }); - const f = join(dir, "mozak.md"); - writeFileSync(f, base); - try { - let called = false; - assert.throws(() => updateFile(f, t => { called = true; return insertTranslation(t, renderTranslation(draft), draft.title); }), e => e.code === "unsupported-legacy-operation"); - assert.equal(called, false); - assert.equal(readFileSync(f, "utf8"), base); - } finally { rmSync(dir, { recursive: true, force: true }); } -}); diff --git a/packages/core/test/vdup-fixture.ts b/packages/core/test/vdup-fixture.ts new file mode 100644 index 0000000..58f9685 --- /dev/null +++ b/packages/core/test/vdup-fixture.ts @@ -0,0 +1,198 @@ +// V-dup public mirror (D3 goal 1). Synthetic plans only: no real plan text. It mirrors the shapes of the private +// set: exact copies under neutral ids, 60 mutations (12 bases x 5 kinds, a third of them Croatian), templated +// siblings that must never be called duplicates, one supersession pair, and one reject moved to another scope. +// Used by packages/core/test/vdup.test.ts (every commit) and scripts/verify-dup.ts (on demand). +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { initScopeState, mutateScope, readScope } from "../src/scope-store.ts"; +import { reviewShow } from "../src/review.ts"; +import { executeOperation } from "../src/api.ts"; +import { loadInventory } from "../src/scope-index.ts"; +import type { SimilarPair, SimilarReport } from "../src/similar.ts"; + +const NOW = "2026-10-20T09:00:00.000Z"; + +interface Base { id: string; title: string; purpose: string; outcomes: [string, string][]; hr: boolean } + +const BASES: Base[] = [ + { id: "cedar-export-2026", hr: false, title: "Cedar export pipeline for quarterly reports", purpose: "Build an export pipeline that turns the Cedar ledger into quarterly PDF reports for the finance team in 2026.", outcomes: [["exporter-runs", "The exporter runs every night without manual steps."], ["pdf-layout", "The quarterly PDF layout matches the finance template."]] }, + { id: "lunar-archive", hr: false, title: "Lunar archive validation suite", purpose: "Check every scanned page in the Lunar archive for missing metadata and broken image files.", outcomes: [["metadata-checked", "Each scanned page has its title, date and source fields."], ["images-verified", "Broken image files are listed with their shelf numbers."]] }, + { id: "harbor-invoices", hr: false, title: "Harbor invoice reconciliation", purpose: "Match Harbor shipping invoices against bank statements and flag the ones that do not reconcile.", outcomes: [["matched", "Invoices and bank lines are matched by amount and reference."], ["flags-reviewed", "Unmatched invoices are flagged for a human review."]] }, + { id: "quartz-telemetry-v2", hr: false, title: "Quartz telemetry transport", purpose: "Move Quartz device telemetry from polling to a push transport with retries and backpressure.", outcomes: [["push-live", "Devices push telemetry through the new transport."], ["retries", "Dropped messages are retried with backoff."]] }, + { id: "orchard-sensors", hr: false, title: "Orchard soil sensor network", purpose: "Install soil moisture sensors across the orchard rows and send readings to a dashboard.", outcomes: [["sensors-installed", "Every row has a working moisture sensor."], ["dashboard", "Readings appear on the irrigation dashboard hourly."]] }, + { id: "maple-onboarding", hr: false, title: "Maple volunteer onboarding guide", purpose: "Write an onboarding guide so new Maple volunteers can run a shift without a mentor present.", outcomes: [["guide-written", "The guide covers opening, shift duties and closing."], ["tested", "Two new volunteers ran a shift using only the guide."]] }, + { id: "comet-scheduler", hr: false, title: "Comet shift scheduler rewrite", purpose: "Rewrite the Comet shift scheduler so swaps and holidays are handled without spreadsheet edits.", outcomes: [["swaps", "Staff can swap shifts inside the scheduler."], ["holidays", "Public holidays block shifts automatically."]] }, + { id: "tundra-backup-2025", hr: false, title: "Tundra photo backup rotation", purpose: "Rotate Tundra photo backups between two offsite disks every month of 2025 and verify restores.", outcomes: [["rotation", "Disks are swapped monthly with a log entry."], ["restore-test", "A sample restore succeeds after each swap."]] }, + { id: "natjecaj-udruge-2026", hr: true, title: "Prijava na natječaj za studentske udruge", purpose: "Pripremiti i predati prijavu na natječaj studentskog zbora za financiranje radionica, uključujući proračun i opis projekta za 2026.", outcomes: [["proracun", "Proračun radionica je usklađen s pravilima natječaja."], ["predano", "Prijava je predana prije roka s potpisima voditelja."]] }, + { id: "ljetna-skola", hr: true, title: "Organizacija ljetne škole programiranja", purpose: "Organizirati tjedan ljetne škole programiranja za srednjoškolce u Đakovu s mentorima i radionicama.", outcomes: [["mentori", "Pet mentora je potvrdilo dolazak u Đakovo."], ["raspored", "Raspored radionica je objavljen učenicima."]] }, + { id: "prirucnik-plaze", hr: true, title: "Prijevod priručnika za čišćenje plaža", purpose: "Prevesti priručnik za volontersko čišćenje plaža na hrvatski i prilagoditi ga lokalnim pravilima o otpadu.", outcomes: [["prijevod", "Cijeli priručnik je preveden na hrvatski jezik."], ["pravila", "Poglavlje o otpadu slijedi lokalna pravila."]] }, + { id: "anketa-smjestaj", hr: true, title: "Analiza ankete o studentskom smještaju", purpose: "Analizirati odgovore ankete o studentskom smještaju i izdvojiti glavne probleme s cijenama i udaljenošću.", outcomes: [["ciscenje", "Odgovori su očišćeni od duplikata i praznih redaka."], ["izvjestaj", "Izvještaj navodi tri glavna problema sa smještajem."]] }, +]; + +const strip = (s: string) => s.replace(/[čć]/g, "c").replace(/[ČĆ]/g, "C").replace(/š/g, "s").replace(/Š/g, "S").replace(/ž/g, "z").replace(/Ž/g, "Z").replace(/đ/g, "d").replace(/Đ/g, "D"); + +function content(title: string, purpose: string, outcomes: [string, string][]) { + return { + constraints: [], nonGoals: [], questions: [], sources: [] as unknown[], + outcomes: outcomes.map(([id, statement]) => ({ acceptance: "objective", criterion: "Synthetic check passes", id, statement })), + purpose, rationale: "Synthetic mirror plan", title, + }; +} + +/** The five mutation kinds, each one a copy that a person would still call the same plan. */ +const MUTATIONS: { kind: string; apply: (b: Base) => { id: string; c: ReturnType } }[] = [ + { kind: "whitespace-punctuation", apply: (b) => ({ id: "m1", c: content(`${b.title}.`, ` ${b.purpose.replace(/ /g, " ").replace(/\.$/, "")} `, b.outcomes) }) }, + { kind: "id-and-year-renumbered", apply: (b) => ({ id: "m2-2031", c: content(b.title, b.purpose.replace(/20\d\d/g, "2031"), b.outcomes) }) }, + { kind: "diacritics-stripped-or-lowercased", apply: (b) => ({ id: "m3", c: b.hr ? content(strip(b.title), strip(b.purpose), b.outcomes.map(([i, s]) => [i, strip(s)] as [string, string])) : content(b.title.toLowerCase(), b.purpose.toLowerCase(), b.outcomes) }) }, + { kind: "outcomes-reordered-one-dropped", apply: (b) => ({ id: "m4", c: content(b.title, b.purpose, [b.outcomes[1]]) }) }, + { kind: "sentence-appended-title-reordered", apply: (b) => ({ id: "m5", c: content(b.title.split(" ").reverse().join(" "), `${b.purpose} ${b.hr ? "Vlasnik dobiva kratki tjedni izvještaj." : "The owner gets a short weekly update."}`, b.outcomes) }) }, +]; + + +/** Templated siblings: same template, different subject. None is a duplicate of another. */ +const TEMPLATES: { scope: string; id: string; c: ReturnType }[] = [ + // Same outcome ids, titles share one word: the template filter drops these. + ...["Cedar study", "Harbor survey", "Quartz model"].map((s, i) => ({ scope: `tmpl-${i + 1}`, id: "manuscript-submitted", c: content(`${s} manuscript`, `The ${s} paper is finished and was submitted to the award committee.`, [["draft", "The paper draft is finished."], ["submitted", "The paper is submitted."]]) })), + // One-line closures. + ...[["grant-completed", "Grant application completed"], ["travel-completed", "Travel stipend completed"], ["lecture-completed", "Lecture recording completed"]].map(([id, title], i) => ({ scope: `tmpl-${i + 1}`, id, c: content(title, `The ${title.toLowerCase().replace(" completed", "")} is completed.`, [["o1", `The ${title.toLowerCase().replace(" completed", "")} is completed.`]]) })), + // Croatian template: titles share three words, subjects differ. + ...["biologije", "kemije"].map((s, i) => ({ scope: `tmpl-${i + 1}`, id: `zavrsni-rad-${s}`, c: content(`Završni rad iz ${s} predan`, `Završni rad iz ${s} je napisan i predan mentoru na pregled.`, [["rad-predan", "Rad je predan mentoru."]]) })), + // Two-outcome research template with unrelated ideas. + ...[["robot-club", "Robotics club for primary schools"], ["garden-planner", "Garden planner for allotments"]].map(([id, title], i) => ({ scope: `tmpl-${i + 1}`, id, c: content(title, `Explore the idea: ${title.toLowerCase()}.`, [["grill-me", "The owner answered the grill-me questions."], ["research", "A research note lists prior work and costs."]]) })), +]; + +export interface Mirror { + base: string; + config: string; + /** "scope/plan" -> family. Same family means a true duplicate pair. */ + family: Map; + templated: Set; + exactCopies: string[][]; + bases: { scope: string; id: string; content: ReturnType }[]; + cleanup(): void; +} + +export function buildMirror(): Mirror { + const base = mkdtempSync(join(process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(), "mozak-vdup-")); + const scopes = ["mirror-a", "copies", "mut-1", "mut-2", "mut-3", "mut-4", "mut-5", "tmpl-1", "tmpl-2", "tmpl-3", "relay-old", "relay-bridge"]; + const entries: Record = {}; + for (const id of scopes) { + const root = join(base, id); + mkdirSync(root); + writeFileSync(join(root, "README.md"), "Synthetic V-dup scope\n"); + writeFileSync(join(root, "AGENTS.md"), "Synthetic instructions\n"); + entries[id] = { id, root }; + initScopeState(entries[id], { operationId: `init-${id}`, scopeId: id, kind: "project", title: `Mirror ${id}`, expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic:init", ownerMessageAt: NOW }); + } + const config = join(base, "inventory.json"); + writeFileSync(config, JSON.stringify({ format: "mozak.local/v3", scopes: scopes.map((id) => ({ id, root: entries[id].root })) })); + let seq = 0; + const change = (scope: string, action: string, payload: unknown, actor: "agent" | "owner" = "agent") => + mutateScope(entries[scope], { operationId: `op-${++seq}`, scopeId: scope, expected: readScope(entries[scope]).snapshot, action, payload }, actor); + const propose = (scope: string, planId: string, c: unknown) => change(scope, "propose", { planId, content: c, distinctFromPlanIds: readScope(entries[scope]).state.plans.map((p) => p.id) }); + const reject = (scope: string, planId: string, reason: string) => { + const shown = reviewShow(readScope(entries[scope]).state, planId, "reject-pending"); + change(scope, "reject-pending", { planId, revisionId: shown.revisionId, reviewDigest: shown.reviewDigest, ownerRef: `synthetic:reject-${++seq}`, ownerMessageAt: NOW, reason }, "owner"); + }; + + const family = new Map(); + const templated = new Set(); + const exactCopies: string[][] = []; + const bases: Mirror["bases"] = []; + BASES.forEach((b, i) => { + const fam = `f${i + 1}`; + const c = content(b.title, b.purpose, b.outcomes); + propose("mirror-a", b.id, c); + bases.push({ scope: "mirror-a", id: b.id, content: c }); + family.set(`mirror-a/${b.id}`, fam); + const copyId = `copy-${String(i + 1).padStart(2, "0")}`; + propose("copies", copyId, c); + family.set(`copies/${copyId}`, fam); + exactCopies.push([`mirror-a/${b.id}`, `copies/${copyId}`]); + MUTATIONS.forEach((m, k) => { + const { id, c: mc } = m.apply(b); + const planId = `${id}-${String(i + 1).padStart(2, "0")}`; + propose(`mut-${k + 1}`, planId, mc); + family.set(`mut-${k + 1}/${planId}`, fam); + }); + }); + for (const t of TEMPLATES) { + propose(t.scope, t.id, t.c); + family.set(`${t.scope}/${t.id}`, `t:${t.scope}/${t.id}`); + templated.add(`${t.scope}/${t.id}`); + } + propose("relay-old", "calendar-relay-v1", content("Calendar relay for the team planner", "Copy team calendar events into the planner through a relay script on the server.", [["relay-script", "The relay script copies new events."], ["two-way", "Edits in the planner flow back to the calendar."]])); + reject("relay-old", "calendar-relay-v1", "Replaced by a bridge design."); + propose("relay-bridge", "sync-bridge-v2", { ...content("Sync bridge between the calendar relay and the team planner", "Replace plan calendar-relay-v1 with a sync bridge that keeps the team calendar and the planner in step.", [["bridge-live", "The bridge syncs events both ways."], ["conflicts", "Conflicting edits are shown to a person."]]), sources: [{ id: "s1", locator: "scope relay-old, plan calendar-relay-v1", anchor: null, observedAt: NOW, version: null, limitations: [] }] }); + family.set("relay-old/calendar-relay-v1", "s:old"); + family.set("relay-bridge/sync-bridge-v2", "s:new"); + propose("mut-5", "moved-placeholder", content("Placeholder for a moved plan", "This draft belongs to another scope.", [["moved", "The plan lives in its new scope."]])); + reject("mut-5", "moved-placeholder", "Moved to scope mirror-a, see there."); + family.set("mut-5/moved-placeholder", "moved"); + return { base, config, family, templated, exactCopies, bases, cleanup: () => rmSync(base, { recursive: true, force: true }) }; +} + +export interface VdupResult { + ok: boolean; + failures: string[]; + metrics: { + plans: number; pairs: number; duplicates: number; truePositive: number; precision: number; recall: number; + familyPairs: number; supersedes: number; overlap: number; templateFiltered: number; templatedDuplicates: number; + exactCopiesInScopeRefused: number; exactCopiesCrossScopeLabelled: number; exactCopies: number; moved: number; ms: number; + }; +} + +const key = (r: { scope: string; planId: string }) => `${r.scope}/${r.planId}`; + +/** Gates from D3 goal 1: in-scope exact copies refused, cross-scope copies labelled duplicate, supersession caught, templates clean, precision >= 0.95. */ +export function verifyMirror(m: Mirror): VdupResult { + const failures: string[] = []; + const inv = loadInventory(m.config); + // Exact copies in scope: proposing a base's content again under a neutral id is refused. + let refused = 0; + for (const b of m.bases) { + const out = executeOperation(inv, "propose", { scope: b.scope, request: { operationId: `copy-try-${b.id}`, scopeId: b.scope, expected: readScope(inv.scopes.find((s) => s.id === b.scope)!).snapshot, action: "propose", payload: { planId: "zz-new", content: b.content } } }); + if (out.exitCode === 3 && out.data.status === "duplicate-plan-candidate") refused++; + else failures.push(`exact copy of ${b.id} was not refused in scope (status ${String(out.data.status)})`); + } + const started = performance.now(); + const out = executeOperation(inv, "similar", { all: true }); + const ms = Math.round(performance.now() - started); + if (out.exitCode !== 0) failures.push(`similar exited ${out.exitCode}`); + const report = out.data.similar as SimilarReport; + const pairs = report.pairs; + const fam = (p: SimilarPair, side: "a" | "b") => m.family.get(key(p[side])); + const dups = pairs.filter((p) => p.label === "duplicate"); + const tp = dups.filter((p) => fam(p, "a") !== undefined && fam(p, "a") === fam(p, "b")).length; + const precision = dups.length ? tp / dups.length : 0; + let familyPairs = 0; + const counts = new Map(); + for (const f of m.family.values()) counts.set(f, (counts.get(f) ?? 0) + 1); + for (const n of counts.values()) familyPairs += (n * (n - 1)) / 2; + const recall = familyPairs ? tp / familyPairs : 0; + if (precision < 0.95) failures.push(`duplicate precision ${precision.toFixed(3)} is below 0.95`); + const templatedDuplicates = dups.filter((p) => m.templated.has(key(p.a)) || m.templated.has(key(p.b))).length; + if (templatedDuplicates) failures.push(`${templatedDuplicates} templated pair(s) labelled duplicate`); + let crossLabelled = 0; + for (const [x, y] of m.exactCopies) { + if (dups.some((p) => [key(p.a), key(p.b)].sort().join() === [x, y].sort().join())) crossLabelled++; + else failures.push(`exact copy ${x} ~ ${y} not labelled duplicate`); + } + const sup = pairs.find((p) => key(p.a) === "relay-bridge/sync-bridge-v2" && key(p.b) === "relay-old/calendar-relay-v1"); + if (!sup || sup.label !== "supersedes-candidate") failures.push(`sync-bridge-v2 over calendar-relay-v1 is ${sup ? sup.label : "missing"}, expected supersedes-candidate`); + if (!report.moved.some((x) => key(x) === "mut-5/moved-placeholder")) failures.push("the reject moved to another scope is not listed"); + if (report.templateFiltered < 1) failures.push("the template filter dropped nothing"); + return { + ok: failures.length === 0, + failures, + metrics: { + plans: report.plans, pairs: pairs.length, duplicates: dups.length, truePositive: tp, precision: Math.round(precision * 1000) / 1000, + recall: Math.round(recall * 1000) / 1000, familyPairs, supersedes: pairs.filter((p) => p.label === "supersedes-candidate").length, + overlap: pairs.filter((p) => p.label === "overlap").length, templateFiltered: report.templateFiltered, templatedDuplicates, + exactCopiesInScopeRefused: refused, exactCopiesCrossScopeLabelled: crossLabelled, exactCopies: m.exactCopies.length, moved: report.moved.length, ms, + }, + }; +} + +export const MUTATION_COUNT = BASES.length * MUTATIONS.length; diff --git a/packages/core/test/vdup.test.ts b/packages/core/test/vdup.test.ts new file mode 100644 index 0000000..9a24624 --- /dev/null +++ b/packages/core/test/vdup.test.ts @@ -0,0 +1,38 @@ +// V-dup on the public synthetic mirror (D3 goal 1). Runs on every commit; scripts/verify-dup.ts runs the same gates. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { canonical } from "../src/understanding.ts"; +import { buildMirror, MUTATION_COUNT, verifyMirror } from "./vdup-fixture.ts"; + +test("V-dup mirror: exact copies caught, 60 mutations, templates clean, supersession labelled, precision >= 0.95", () => { + assert.equal(MUTATION_COUNT, 60); + const m = buildMirror(); + try { + const r = verifyMirror(m); + assert.deepEqual(r.failures, []); + assert.equal(r.metrics.exactCopiesInScopeRefused, 12); + assert.equal(r.metrics.exactCopiesCrossScopeLabelled, 12); + assert.equal(r.metrics.templatedDuplicates, 0); + assert.ok(r.metrics.precision >= 0.95, `precision ${r.metrics.precision}`); + assert.ok(r.ok); + } finally { + m.cleanup(); + } +}); + +test("V-dup mirror fails loudly when the supersession pair is gone", () => { + const m = buildMirror(); + try { + const path = join(m.base, "relay-bridge", "mozak.json"); + const state = JSON.parse(readFileSync(path, "utf8")); + state.plans = []; + writeFileSync(path, canonical(state)); + const r = verifyMirror(m); + assert.equal(r.ok, false); + assert.deepEqual(r.failures, ["sync-bridge-v2 over calendar-relay-v1 is missing, expected supersedes-candidate"]); + } finally { + m.cleanup(); + } +}); diff --git a/packages/core/test/vref.test.ts b/packages/core/test/vref.test.ts new file mode 100644 index 0000000..de8f635 --- /dev/null +++ b/packages/core/test/vref.test.ts @@ -0,0 +1,235 @@ +// V-ref verifier tests (D3 goal 2): every ref resolves via a plan or mergedPlanId or is reported; mozak.md is +// byte-identical with and without the sidecar; the unchanged 0.4.0 code path reads and writes a scope with a sidecar; +// `ready` is exact on a synthetic chain; check reports every annotation rule. Synthetic temp scopes only. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cleanup, world } from "./annotations-fixture.ts"; +import { readScope, renderBridge } from "../src/scope-store.ts"; +import { canonical } from "../src/understanding.ts"; +import { ANNOTATIONS_FILE, readAnnotations } from "../src/annotations.ts"; + +after(cleanup); +type Issue = { code: string; message: string }; +const ref = (planId: string, target: string, relation = "needs", extra: Record = {}) => ({ kind: "ref", planId, target, relation, evidence: `Synthetic evidence for ${planId}.`, ...extra }); + +function mulberry32(seed: number) { + return () => { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; +} + +/** Owner hand edit: drop plans from mozak.json without mozak (like the hand-removed rejected plans in the real vault). */ +function handRemove(root: string, planIds: string[]) { + const path = join(root, "mozak.json"); + const state = JSON.parse(readFileSync(path, "utf8")); + state.plans = state.plans.filter((p: { id: string }) => !planIds.includes(p.id)); + writeFileSync(path, canonical(state)); +} + +test("V-ref property: every ref resolves through a plan or mergedPlanId, or check reports it (16 seeded worlds)", (t) => { + const totals = { refs: 0, plan: 0, merged: 0, reported: 0, unaccounted: 0 }; + for (let seed = 1; seed <= 16; seed++) { + const rnd = mulberry32(seed); + const pick = (xs: T[]) => xs[Math.floor(rnd() * xs.length)]!; + const w = world(["alpha", "beta"], { annotations: true }); + const plans: Record = { alpha: [], beta: [] }; + for (const scope of ["alpha", "beta"]) { + const n = 3 + Math.floor(rnd() * 3); + for (let i = 0; i < n; i++) { const id = `${scope[0]}${i}`; w.propose(scope, id, { outcomes: [{ id: "one" }, { id: "two" }] }); plans[scope].push(id); } + } + for (const scope of ["alpha", "beta"]) { + const items: unknown[] = []; + const used = new Set(); + for (let k = 0; k < 5; k++) { + const from = pick(plans[scope]); + const toScope = pick(["alpha", "beta"]); + const to = pick(plans[toScope]); + if (toScope === scope && to === from) continue; + const target = `${toScope}/${to}${rnd() < 0.3 ? `#${pick(["one", "two"])}` : ""}`; + const relation = pick(["needs", "informs", "supersedes"]); + const fromOutcome = rnd() < 0.3 ? pick(["one", "two"]) : undefined; + const key = JSON.stringify([from, target, relation, fromOutcome]); + if (used.has(key)) continue; + used.add(key); + items.push(ref(from, target, relation, fromOutcome ? { fromOutcome } : {})); + } + if (items.length) assert.equal(w.annotate(scope, items).exitCode, 0, `seed ${seed}`); + } + // Churn after annotating: merges fold plans away, hand edits drop plans. + for (const scope of ["alpha", "beta"]) { + if (rnd() < 0.6 && plans[scope].length >= 3) { + const [target, source] = [plans[scope][0]!, plans[scope][plans[scope].length - 1]!]; + assert.equal(w.merge(scope, target, source).committed, true, `seed ${seed} merge`); + plans[scope] = plans[scope].filter((p) => p !== source); + } + if (rnd() < 0.5 && plans[scope].length >= 2) { + const gone = plans[scope][1]!; + handRemove(w.entries[scope].root, [gone]); + plans[scope] = plans[scope].filter((p) => p !== gone); + } + } + const reported = new Map(); + for (const scope of ["alpha", "beta"]) reported.set(scope, w.op("check", { scope }).data.issues as Issue[]); + const graph = w.op("graph", { all: true }).data.graph as { edges: { id: string; from: string; target: string; relation: string; resolution: { status: string; via?: string; scope: string; planId: string; outcomeId?: string; mergedFrom?: string } }[] }; + for (const e of graph.edges) { + totals.refs++; + const r = e.resolution; + if (r.status === "resolved") { + const state = readScope(w.entries[r.scope]).state; + const plan = state.plans.find((p) => p.id === r.planId); + assert.ok(plan, `seed ${seed}: ${e.target} resolved to a live plan`); + if (r.via === "merged") { + assert.ok(plan!.decisions.some((d) => d.mergedPlanId === r.mergedFrom), `seed ${seed}: merged resolution names a real mergedPlanId`); + totals.merged++; + } else { + if (r.outcomeId) assert.ok((plan!.accepted ?? plan!.pending)!.content.outcomes.some((o) => o.id === r.outcomeId)); + totals.plan++; + } + } else { + const scope = e.from.slice(0, e.from.indexOf("/")); + const found = reported.get(scope)!.some((i) => (i.code === "ref-dangling" || i.code === "ref-target-unavailable") && i.message.includes(e.target)); + if (found) totals.reported++; else totals.unaccounted++; + } + } + } + t.diagnostic(`V-ref property: ${JSON.stringify(totals)}`); + assert.equal(totals.unaccounted, 0); + assert.ok(totals.refs >= 80 && totals.merged > 0 && totals.reported > 0, JSON.stringify(totals)); +}); + +test("V-ref: mozak.md is byte-identical with and without the sidecar", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); w.propose("alpha", "c"); + const bridge = () => readFileSync(join(w.entries.alpha.root, "mozak.md")); + const without = bridge(); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b"), ref("b", "alpha/c", "supersedes"), { kind: "deadline", planId: "c", date: "2099-01-01", evidence: "Due 2099-01-01." }]).exitCode, 0); + assert.deepEqual(bridge(), without, "annotate leaves mozak.md untouched"); + assert.equal(w.op("render", { scope: "alpha" }).data.status, "ok"); + assert.deepEqual(bridge(), without, "render with a sidecar present writes nothing new"); + w.pass("alpha", "a", "done"); + const withSidecar = bridge(); + const read = readScope(w.entries.alpha); + assert.equal(read.projectionStatus, "current"); + unlinkSync(join(w.entries.alpha.root, ANNOTATIONS_FILE)); + assert.deepEqual(Buffer.from(renderBridge(readScope(w.entries.alpha).state, read.snapshot.graphHash, "mozak.json")), withSidecar, "the renderer output does not depend on the sidecar"); + assert.equal(readScope(w.entries.alpha).projectionStatus, "current"); +}); + +test("V-ref: the unchanged 0.4.0 core (main) reads and writes a scope that has a sidecar", async (t) => { + let hasMain = true; + try { execFileSync("git", ["rev-parse", "--verify", "-q", "main^{commit}"], { stdio: "ignore", timeout: 5000 }); } catch { hasMain = false; } + if (!hasMain) { t.skip("branch main is not available in this checkout"); return; } + const version = JSON.parse(execFileSync("git", ["show", "main:package.json"], { encoding: "utf8", timeout: 5000 })).version; + const dir = mkdtempSync(join(process.env.TMPDIR!, "mozak-main-core-")); + try { + execFileSync("sh", ["-c", `git archive main packages/core/src | tar -x -C "${dir}"`], { timeout: 20000 }); + const old = await import(join(dir, "packages/core/src/index.ts")); + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + assert.equal(w.annotate("alpha", [ref("a", "alpha/b")]).exitCode, 0); + const sidecar = readFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE)); + const inv = old.loadInventory(w.config); + const ctx = old.executeOperation(inv, "context", { scope: "alpha" }); + assert.equal(ctx.exitCode, 0, `main ${version} context`); + assert.equal(old.executeOperation(inv, "check", { scope: "alpha" }).exitCode, 0, `main ${version} check is clean`); + const plans = old.executeOperation(inv, "plans", { scope: "alpha" }); + assert.equal(plans.exitCode, 0); + const write = old.executeOperation(inv, "propose", { scope: "alpha", request: { operationId: "old-client-write", scopeId: "alpha", expected: ctx.data.snapshot, action: "propose", payload: { planId: "c", content: { title: "Old client synthetic plan", purpose: "p", outcomes: [{ id: "o", statement: "s", acceptance: "objective", criterion: "c" }], constraints: [], nonGoals: [], rationale: "r", questions: [], sources: [] } } } }); + assert.equal(write.exitCode, 0, JSON.stringify(write.data)); + assert.deepEqual(readFileSync(join(w.entries.alpha.root, ANNOTATIONS_FILE)), sidecar, "old client leaves the sidecar alone"); + assert.equal(readScope(w.entries.alpha).projectionStatus, "current"); + assert.equal(readAnnotations(w.entries.alpha.root, "alpha").doc!.plans.a.refs.length, 1); + t.diagnostic(`old client: main core ${version} context, check, plans and propose ok with a sidecar present`); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("V-ref: ready is exact on a synthetic chain", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); w.propose("alpha", "c", { outcomes: [{ id: "first" }, { id: "second" }] }); + w.propose("alpha", "d"); w.propose("alpha", "e", { outcomes: [{ id: "x" }, { id: "y" }] }); + w.propose("alpha", "f"); w.propose("alpha", "g"); + assert.equal(w.annotate("alpha", [ + ref("a", "alpha/b"), ref("b", "alpha/c"), ref("d", "alpha/c#second"), + ref("e", "alpha/c", "needs", { fromOutcome: "y" }), ref("f", "alpha/g", "supersedes"), ref("g", "alpha/a", "informs"), + ]).exitCode, 0); + const ready = () => { + const r = w.op("ready", { scope: "alpha" }).data.ready as { ready: { planId: string }[]; blocked: { planId: string }[]; superseded: { planId: string; by: string[] }[] }; + return { ready: r.ready.map((x) => x.planId).sort(), blocked: r.blocked.map((x) => x.planId).sort(), superseded: r.superseded.map((x) => `${x.planId}<${x.by.join(",")}`) }; + }; + assert.deepEqual(ready(), { ready: ["c", "e", "f"], blocked: ["a", "b", "d"], superseded: ["g { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "late", { purpose: "Ship the synthetic report by 2099-09-01." }); + w.propose("alpha", "soon"); + w.propose("alpha", "free"); + w.propose("alpha", "hub"); + w.propose("alpha", "user1"); w.propose("alpha", "user2"); + assert.equal(w.annotate("alpha", [{ kind: "deadline", planId: "soon", date: "2099-02-01", evidence: "Owner said 1 Feb 2099." }, ref("user1", "alpha/hub"), ref("user2", "alpha/hub")]).exitCode, 0); + const r = w.op("ready", { scope: "alpha" }).data.ready as { ready: { planId: string; deadline: string | null; deadlineStatus: string }[] }; + assert.deepEqual(r.ready.map((x) => [x.planId, x.deadline, x.deadlineStatus]), [["soon", "2099-02-01", "owner"], ["late", "2099-09-01", "inferred"], ["hub", null, "none"], ["free", null, "none"]]); +}); + +test("refs to a merged plan resolve through mergedPlanId", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "x"); w.propose("alpha", "y"); w.propose("alpha", "z"); + assert.equal(w.annotate("alpha", [ref("x", "alpha/y")]).exitCode, 0); + w.merge("alpha", "z", "y"); + const edge = (w.op("graph", { scope: "alpha" }).data.graph as { edges: { resolution: unknown }[] }).edges[0]; + assert.deepEqual(edge.resolution, { status: "resolved", via: "merged", scope: "alpha", planId: "z", mergedFrom: "y" }); + assert.equal((w.op("check", { scope: "alpha" }).data.issues as Issue[]).some((i) => i.code === "ref-dangling"), false); +}); + +test("check reports dangling refs, needs cycles, needs to rejected or completed plans, superseded open plans and next actions", () => { + const w = world(["alpha", "beta"], { annotations: true }); + for (const id of ["a", "b", "c", "done", "old", "new", "gone"]) w.propose("alpha", id); + w.propose("alpha", "draft", {}, false); + w.propose("beta", "remote-peer"); + assert.equal(w.annotate("alpha", [ + ref("a", "alpha/b"), ref("b", "alpha/a"), ref("c", "alpha/draft"), ref("c", "alpha/done"), + ref("new", "alpha/old", "supersedes"), ref("a", "alpha/gone", "informs"), ref("a", "beta/remote-peer", "informs"), + ]).exitCode, 0); + w.reject("alpha", "draft"); + w.complete("alpha", "done"); + handRemove(w.entries.alpha.root, ["gone"]); + handRemove(w.entries.beta.root, ["remote-peer"]); + const check = w.op("check", { scope: "alpha" }); + assert.equal(check.exitCode, 3); + const codes = (check.data.issues as Issue[]).filter((i) => !["bridge-conflict", "bridge-stale"].includes(i.code)); + const by = (code: string) => codes.filter((i) => i.code === code).map((i) => i.message); + assert.equal(by("ref-dangling").length, 2); + assert.ok(by("ref-dangling").some((m) => m.includes("alpha/gone")) && by("ref-dangling").some((m) => m.includes("beta/remote-peer"))); + assert.deepEqual(by("needs-cycle"), ["needs cycle: alpha/a -> alpha/b -> alpha/a"]); + assert.equal(by("needs-closed-target").length, 2); + assert.ok(by("needs-closed-target").some((m) => m.includes("rejected")) && by("needs-closed-target").some((m) => m.includes("completed"))); + assert.equal(by("superseded-open").length, 1); + assert.equal(by("superseded-next-action").length, 1); + assert.match(by("superseded-next-action")[0]!, /alpha\/old is superseded by alpha\/new/); +}); + +test("graph lists nodes, edges and counts across scopes", () => { + const w = world(["alpha", "beta"], { annotations: true }); + w.propose("alpha", "a"); w.propose("beta", "b", { outcomes: [{ id: "k" }] }); + assert.equal(w.annotate("alpha", [ref("a", "beta/b#k", "informs")]).exitCode, 0); + const one = w.op("graph", { scope: "alpha" }); + assert.equal(one.exitCode, 0); + const g = one.data.graph as { nodes: { id: string }[]; edges: { from: string; to: string }[]; counts: Record }; + assert.deepEqual(g.nodes.map((n) => n.id), ["alpha/a", "beta/b"]); + assert.deepEqual(g.edges.map((e) => [e.from, e.to]), [["alpha/a", "beta/b"]]); + assert.deepEqual(g.counts, { nodes: 2, edges: 1, dangling: 0, unavailable: 0 }); + assert.deepEqual((one.data.annotations as Record).alpha, w.token("alpha")); + assert.equal(w.op("graph", {}).exitCode, 2); +}); diff --git a/packages/core/test/write.test.ts b/packages/core/test/write.test.ts deleted file mode 100644 index 51c557c..0000000 --- a/packages/core/test/write.test.ts +++ /dev/null @@ -1,28 +0,0 @@ -import { test } from "node:test"; -import assert from "node:assert/strict"; -import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { guardedWrite, hashText, readSnapshot, updateFile } from "../src/write.ts"; - -const fresh = () => join(mkdtempSync(join(process.env.JCODE_SCRATCH_DIR ?? tmpdir(), "mozak-retired-write-")), "mozak.md"); -test("legacy snapshot/hash helpers remain read-only", () => { - const file = fresh(); - assert.equal(readSnapshot(file).hash, hashText("")); - assert.deepEqual(readdirSync(join(file, "..")), []); - writeFileSync(file, "original\n"); - assert.equal(readSnapshot(file).text, "original\n"); -}); -test("retired raw Markdown writer refuses without creating files or locks", () => { - const file = fresh(); - assert.throws(() => guardedWrite(file, "injected", hashText("")), { code: "unsupported-legacy-operation" }); - assert.deepEqual(readdirSync(join(file, "..")), []); -}); -test("retired transform writer never evaluates its callback or changes existing content", () => { - const file = fresh(); writeFileSync(file, "protected\n"); - let called = false; - assert.throws(() => updateFile(file, () => { called = true; return "injected"; }), { code: "unsupported-legacy-operation" }); - assert.equal(called, false); - assert.equal(readFileSync(file, "utf8"), "protected\n"); - assert.deepEqual(readdirSync(join(file, "..")), ["mozak.md"]); -}); diff --git a/packages/core/test/writer-child.ts b/packages/core/test/writer-child.ts deleted file mode 100644 index 32b3779..0000000 --- a/packages/core/test/writer-child.ts +++ /dev/null @@ -1,7 +0,0 @@ -// Child process for the concurrency test: appends N numbered lines to a shared file through updateFile. -import { updateFile } from "../src/index.ts"; - -const [file, tag, count] = process.argv.slice(2); -for (let i = 0; i < Number(count); i++) { - updateFile(file, (t) => t + `${tag}-${i}\n`); -} diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 3ecb245..a926467 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@mozak/mcp", - "version": "0.4.8", + "version": "0.5.0", "type": "module", "main": "dist/index.js", "bin": { @@ -10,6 +10,6 @@ "node": ">=24.11.0" }, "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" } } diff --git a/packages/mcp/src/server.ts b/packages/mcp/src/server.ts index 2a259a8..8b49af3 100644 --- a/packages/mcp/src/server.ts +++ b/packages/mcp/src/server.ts @@ -2,7 +2,7 @@ // Core validation is authoritative. This layer only closes the advertised surface: // fixed tool names, closed argument objects, a fixed agent actor and no config input. -import { decideWithFlags, executeOperation, planShow, type OperationOutput, type ScopeInventory } from "@mozak/core"; +import { decideWithFlags, executeOperation, focusList, planShow, type OperationOutput, type ScopeInventory } from "@mozak/core"; import { readFileSync } from "node:fs"; /** This package's version, reported in the MCP handshake. */ @@ -29,6 +29,7 @@ export interface Runtime { const HELPERS: Record) => OperationOutput> = { "plan-show": planShow, "decide-flags": decideWithFlags, + focus: focusList, }; interface PropertySpec { @@ -78,9 +79,31 @@ export const TOOLS: ToolDef[] = [ includeRejected: { type: "boolean", description: "Include rejected drafts." }, limit: { type: "integer", description: "Page size per group." }, continuation: { type: "string", description: "Opaque continuation token from a previous page." }, + sort: { type: "string", enum: ["deadline"], description: "Order rows by owner or inferred deadline, earliest first; rows gain deadline fields." }, }, [], ), + tool( + "mozak_plan_graph", + "graph", + "Cross-plan references from owner annotations (needs, informs, supersedes) with how each target resolves: live plan, merged plan, dangling or unavailable. Plans carry their deadline. Read-only; annotations are written only by the owner.", + { scope: SCOPE, all: { type: "boolean", description: "Every inventoried scope instead of one." } }, + [], + ), + tool( + "mozak_ready", + "ready", + "Open plans whose needs are met, ordered by deadline, then by how many plans need them. Blocked plans list what they wait on; superseded plans are listed apart. Advisory only: needs never refuse a write.", + { scope: SCOPE, all: { type: "boolean", description: "Every inventoried scope instead of one." } }, + [], + ), + tool( + "mozak_similar", + "similar", + "Similar plans pooled across one scope or every scope, labelled duplicate, overlap or supersedes-candidate, with templated siblings filtered out and rejects whose reason says moved to listed apart. Lexical rules only, no stored state. Read-only: merging, rejecting or linking stays an owner decision.", + { scope: SCOPE, all: { type: "boolean", description: "Every inventoried scope instead of one." } }, + [], + ), tool( "mozak_scopes", "scopes", @@ -119,6 +142,13 @@ export const TOOLS: ToolDef[] = [ scope: SCOPE, plan: { type: "string", description: "Exact plan ID." }, }, ["scope", "plan"]), + tool( + "mozak_focus", + "focus", + "The owner's focus list: plan ids starred per scope in the inventory. A sidebar marker for the owner, read-only here. It grants nothing and does not change plan state; only the owner stars or unstars plans.", + { scope: SCOPE }, + [], + ), tool( "mozak_propose", "propose", diff --git a/packages/mcp/test/annotations-mcp.test.ts b/packages/mcp/test/annotations-mcp.test.ts new file mode 100644 index 0000000..fb54f0b --- /dev/null +++ b/packages/mcp/test/annotations-mcp.test.ts @@ -0,0 +1,37 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { executeOperation } from "../../core/src/api.ts"; +import { handle, TOOLS } from "../src/server.ts"; +import { cleanup, world } from "../../core/test/annotations-fixture.ts"; + +after(cleanup); + +function call(rt: Parameters[1], name: string, args: Record) { + const reply = handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, rt) as { result: { content: { text: string }[]; isError?: boolean } }; + const text = reply.result.content[0]!.text; + let data: any = text; + try { data = JSON.parse(text); } catch { /* argument errors are plain text */ } + return { isError: reply.result.isError === true, data }; +} + +test("MCP: mozak_plan_graph, mozak_ready and plans sort read annotations; annotate is not reachable", () => { + const w = world(["alpha"], { annotations: true }); + w.propose("alpha", "a"); w.propose("alpha", "b"); + assert.equal(w.annotate("alpha", [{ kind: "ref", planId: "b", target: "alpha/a", relation: "needs", evidence: "Synthetic: b needs a." }]).exitCode, 0); + const rt = { inventory: w.inv(), execute: executeOperation }; + const graph = call(rt, "mozak_plan_graph", { scope: "alpha" }); + assert.equal(graph.isError, false); + assert.equal(graph.data.graph.counts.edges, 1); + const ready = call(rt, "mozak_ready", { scope: "alpha" }); + assert.deepEqual(ready.data.ready.ready.map((r: { planId: string }) => r.planId), ["a"]); + assert.deepEqual(ready.data.ready.blocked.map((r: { planId: string }) => r.planId), ["b"]); + const plans = call(rt, "mozak_plans", { scope: "alpha", sort: "deadline" }); + assert.equal(plans.isError, false); + assert.equal(call(rt, "mozak_plans", { scope: "alpha", sort: "title" }).isError, true); + assert.equal(TOOLS.some((t) => t.op === "annotate"), false); + // Even a direct agent call through the shared facade is refused before any file is touched. + const before = w.token("alpha"); + const refused = executeOperation(w.inv(), "annotate", { scope: "alpha", request: {} }, "agent"); + assert.equal(refused.data.status, "not-permitted"); + assert.deepEqual(w.token("alpha"), before); +}); diff --git a/packages/mcp/test/focus-mcp.test.ts b/packages/mcp/test/focus-mcp.test.ts new file mode 100644 index 0000000..940e11f --- /dev/null +++ b/packages/mcp/test/focus-mcp.test.ts @@ -0,0 +1,33 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { executeOperation } from "../../core/src/api.ts"; +import { setFocus } from "../../core/src/focus.ts"; +import { handle, TOOLS } from "../src/server.ts"; +import { cleanup, world } from "../../core/test/annotations-fixture.ts"; + +after(cleanup); + +function call(rt: Parameters[1], name: string, args: Record) { + const reply = handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, rt) as { result: { content: { text: string }[]; isError?: boolean } }; + const text = reply.result.content[0]!.text; + let data: any = text; + try { data = JSON.parse(text); } catch { /* argument errors are plain text */ } + return { isError: reply.result.isError === true, data }; +} + +test("MCP: mozak_focus reads the focus lists, read-only; no tool writes focus", () => { + const w = world(["alpha", "beta"]); + w.propose("alpha", "a1"); + setFocus(w.config, { scope: "alpha", plan: "a1", action: "add" }); + const before = readFileSync(w.config, "utf8"); + const rt = { inventory: w.inv(), execute: executeOperation }; + assert.deepEqual(call(rt, "mozak_focus", {}).data.focus, { alpha: ["a1"], beta: [] }); + assert.deepEqual(call(rt, "mozak_focus", { scope: "alpha" }).data.focus, { alpha: ["a1"] }); + const missing = call(rt, "mozak_focus", { scope: "gamma" }); + assert.equal(missing.isError, true); + assert.match(JSON.stringify(missing.data), /scope-not-found/); + assert.equal(call(rt, "mozak_focus", { scope: "alpha", plan: "a1" }).isError, true, "no extra arguments"); + assert.equal(readFileSync(w.config, "utf8"), before); + assert.deepEqual(TOOLS.filter((t) => /focus/.test(t.name)).map((t) => t.name), ["mozak_focus"]); +}); diff --git a/packages/mcp/test/mcp.test.ts b/packages/mcp/test/mcp.test.ts index f193b0b..27eccd8 100644 --- a/packages/mcp/test/mcp.test.ts +++ b/packages/mcp/test/mcp.test.ts @@ -12,13 +12,17 @@ import { initScopeState, loadInventory } from "@mozak/core"; // Read tools map to API operations; mutation tools map to API operations; every call is actor "agent". const READ_TOOLS: Record = { mozak_context: { op: "context", args: ["scope", "brief", "plan"], required: ["scope"] }, - mozak_plans: { op: "plans", args: ["scope", "all", "includeRejected", "limit", "continuation"], required: [] }, + mozak_plans: { op: "plans", args: ["scope", "all", "includeRejected", "limit", "continuation", "sort"], required: [] }, + mozak_plan_graph: { op: "graph", args: ["scope", "all"], required: [] }, + mozak_ready: { op: "ready", args: ["scope", "all"], required: [] }, + mozak_similar: { op: "similar", args: ["scope", "all"], required: [] }, mozak_scopes: { op: "scopes", args: [], required: [] }, mozak_sync: { op: "sync", args: ["scope"], required: [] }, mozak_review_show: { op: "review", args: ["scope", "plan", "purpose", "outcome"], required: ["scope", "plan"] }, mozak_check: { op: "check", args: ["scope"], required: ["scope"] }, mozak_operation: { op: "operation", args: ["scope", "id"], required: ["scope", "id"] }, mozak_plan_show: { op: "plan-show", args: ["scope", "plan"], required: ["scope", "plan"] }, + mozak_focus: { op: "focus", args: ["scope"], required: [] }, }; const MUTATION_TOOLS: Record = { mozak_propose: { op: "propose" }, @@ -40,6 +44,9 @@ const FORBIDDEN = [ "mozak_review_decide", "mozak_approve_direction", "mozak_projection_repair", + "mozak_focus_add", + "mozak_focus_remove", + "mozak_set_focus", ]; const SYNTHETIC_OWNER = "synthetic-owner:test-fixture"; @@ -174,7 +181,7 @@ async function snapshotOf(s: Server): Promise<{ revision: string; graphHash: str // ---- tool metadata ------------------------------------------------------- -test("tools/list advertises exactly the thirteen permitted tools", () => { +test("tools/list advertises exactly the fifteen permitted tools", () => { const r = handle({ jsonrpc: "2.0", id: 1, method: "tools/list" }, { inventory: emptyInventory(), execute: spyExecute().execute }) as { result: { tools: { name: string }[] }; }; diff --git a/packages/obsidian/README.md b/packages/obsidian/README.md index 42fd4df..c81ce9d 100644 --- a/packages/obsidian/README.md +++ b/packages/obsidian/README.md @@ -1,15 +1,17 @@ # mozak Obsidian plugin -Read-only Obsidian sidebar for [mozak](../../README.md). Shows every scope from your `mozak-inventory.json`, its plans, and each plan's progress strip. Clicking a plan opens its section in the scope's `mozak.md` note (`purpose`, outcome roadmap, status table, and full plan). +Obsidian sidebar for [mozak](../../README.md). Shows every scope from your `mozak-inventory.json`, its plans, and each plan's progress strip. Clicking a plan opens its section in the scope's `mozak.md` note (`purpose`, outcome roadmap, status table, and full plan). It never writes plan state. ## Use - Ribbon icon (**Open mozak scopes**) or command (**mozak: Open scopes**) opens the sidebar. It refreshes on open, when plan files change on disk, and when you click the refresh button. -- Filter by **All**, **Open** (open, awaiting approval, paused), or **Done** (completed). +- Tabs: **Open** (open, awaiting approval, paused), **Focus** (plans you starred that are still open) and **Done** (completed). A focused plan that completes shows only under Done. Rejected plans show in no tab (`mozak plans --include-rejected` still lists them). The sidebar opens on Focus when it has plans, else Open, and remembers the last tab you chose. +- Click the star on a plan row to add it to Focus or take it out. Clicking the rest of the row still opens the plan. The star writes only the scope's `focus` list in `mozak-inventory.json` (the same as `mozak focus add|remove`). Focus is a marker for you: agents can read it but never change it, and it is not plan state. - Search filters by scope title, scope id, or plan title. Matching scopes open automatically while searching. - Each open plan row shows a small outcome strip (green = done, gold = evidence recorded, purple = current stop, faint = not started) and `done/total`. - Click a plan row to open its `## Title · \`plan-id\`` section in the scope's `mozak.md` note (or its line under `## Completed` for completed plans). If the scope is outside the current vault, the plugin opens `mozak.md` in your system default viewer. - Each GitHub remote scope shows a `globe` (public) or `lock` (private) badge, plus quick links to its GitHub repository and `README.md`. +- When annotations are on for a scope (off by default, see [docs/annotations.md](../../docs/annotations.md)) and the owner has added cross-plan refs with `mozak annotate`, a plan row lists them: what it needs, informs or supersedes, both ways. Display only. The plugin never writes `mozak.annotations.json`. - Settings (**Settings → mozak**): - **Inventory path**: path to `mozak-inventory.json` (leave empty to auto-discover by walking upward from the vault root). - **Auto-refresh**: watch `mozak-inventory.json` and each scope's `mozak.json` / `mozak.md` with `fs.watch` and redraw on change. @@ -18,18 +20,19 @@ Read-only Obsidian sidebar for [mozak](../../README.md). Shows every scope from ## Disclosures (Obsidian community plugin policy) - **Desktop only (`isDesktopOnly: true`).** The plugin uses Node.js APIs (`node:fs`, `node:path`, `node:child_process`) to read your local scope files and optional git remotes. -- **Files accessed outside the vault.** When your `mozak-inventory.json` lists scopes outside the current vault (for example local code repositories or other folders you own), the plugin reads their `mozak.json`, `mozak.md`, `README.md`, and `AGENTS.md` files from those configured paths, and watches them when **Auto-refresh** is enabled. It never scans or crawls directories not listed in `mozak-inventory.json`. -- **What the plugin writes.** The plugin never modifies canonical plan state (`mozak.json`) and never approves or mutates plans. When a scope's derived `mozak.md` note is out of date with its `mozak.json` and has no unmerged hand edits, the plugin regenerates `mozak.md` on disk (the same projection as `mozak render`). +- **Files accessed outside the vault.** When your `mozak-inventory.json` lists scopes outside the current vault (for example local code repositories or other folders you own), the plugin reads their `mozak.json`, `mozak.md`, `mozak.annotations.json` (when present and annotations are on for that scope), `README.md`, and `AGENTS.md` files from those configured paths, and watches them when **Auto-refresh** is enabled. It never scans or crawls directories not listed in `mozak-inventory.json`. To find the inventory when **Inventory path** is empty, it checks whether a file named `mozak-inventory.json` exists in the vault folder and in each parent folder up to the filesystem root. It only checks that one file name and reads the first match. +- **What the plugin writes.** The plugin never modifies canonical plan state (`mozak.json`) and never approves or mutates plans. It writes two things: when a scope's derived `mozak.md` note is out of date with its `mozak.json` and has no unmerged hand edits, it regenerates `mozak.md` on disk (the same projection as `mozak render`), and the star toggle edits the `focus` list of that scope's entry in `mozak-inventory.json` under the inventory lock (every other key and the entry order stay as they were). - **Network and child-process activity.** - 1. If your inventory contains remote GitHub scopes (`"remote": "github:owner/repo"` without vault-hosted `"plans"`), the plugin runs your local `git` binary with your existing git credentials to refresh cached scope files in a `.mozak-cache` folder next to your `mozak-inventory.json`: `git fetch`, then a reset of that cache copy to the fetched commit (`git reset --hard`, only inside `.mozak-cache`). If an earlier mozak write left a `mozak.json` / `mozak.md` change uncommitted or unpushed in that cache (for example after a network failure), the sync first commits and pushes that pending plan change, and nothing else. This happens when you click **Sync remote scopes**, and in the background every **Repo sync interval (seconds)** while **Auto-refresh** is on. The default is every 60 seconds. Set the interval to `0` to turn background git activity off. With no remote scopes the plugin runs no git command. - 2. The same sync asks the public GitHub API (`https://api.github.com/repos/OWNER/REPO`, no login, through your local `curl` with a 5 second timeout) whether each remote GitHub scope is public. It asks at most once per 24 hours per scope and stores the answer in that scope's `.mozak-cache` meta file. The answer drives the public or private badge and the warning when plans would be published in a public repo. Local scopes are never checked. - 3. **Update notice.** The plugin makes no network call for this. It only reads `~/.local/state/mozak/update.json` (or `$XDG_STATE_HOME/mozak/update.json`), which the installed mozak CLI writes after it checks `https://api.github.com/repos/pitfa19/mozak/tags` at most once per 24 hours. When that file names a newer release, the sidebar shows one line such as `mozak X.Y.Z available`. Set `MOZAK_NO_UPDATE_CHECK=1` to turn the CLI check and the notice off. + 1. If your inventory contains remote GitHub scopes (`"remote": "github:owner/repo"` without vault-hosted `"plans"`), the plugin runs your local `git` binary with your existing git credentials on its `.mozak-cache` copy: `git fetch`, then reset that cache to the fetched commit. If an earlier write left a pending `mozak.json` / `mozak.md` change, sync first commits and pushes that plan change, and nothing else. This happens when you click **Sync vaults and repos**, and in the background every **Repo sync interval (seconds)** while **Auto-refresh** is on. The default is every 60 seconds. Set the interval to `0` to turn background git fetches off. + 2. **Sync vaults and repos** also syncs each git repository (for example a vault) that holds a local scope, the same as `mozak sync --local`: `git fetch` from that repository's upstream, then `git merge --ff-only` while holding the mozak write locks of every scope inside it. It never pushes, never rebases and never merges a diverged history: a vault with local commits is reported as having unpushed commits, and a diverged vault is reported and left alone. This only happens when you click the button, never in the background. With no remote scopes and no local scope inside a git repository, the plugin runs no git command. + 3. The same sync asks the public GitHub API (`https://api.github.com/repos/OWNER/REPO`, no login, through your local `curl` with a 5 second timeout) whether each remote GitHub scope is public. This includes vault-plans scopes (`"plans"` set), which are never fetched with git but still get the badge. It asks at most once per 24 hours per scope (once per hour while the answer is unknown) and stores the answer in that scope's `.mozak-cache` meta file. The answer drives the public or private badge and the warning when plans would be published in a public repo. Local scopes are never checked. + 4. **Update notice.** The plugin makes no network call for this. It only reads `~/.local/state/mozak/update.json` (or `$XDG_STATE_HOME/mozak/update.json`), which the installed mozak CLI writes after it checks `https://api.github.com/repos/pitfa19/mozak/tags` at most once per 24 hours. When that file names a newer release, the sidebar shows one line such as `mozak X.Y.Z available`. Set `MOZAK_NO_UPDATE_CHECK=1` to turn the CLI check and the notice off. - **No self-update.** The plugin never installs or updates itself, the CLI or anything else. Updates come through Obsidian's Community plugins screen or `mozak upgrade`, which you run yourself. - **No telemetry, accounts, payments, ads or cloud service.** All plans and evidence stay in your local folders and git repositories. ## Build and install -From the repository root: +The plugin is not in the Obsidian community directory yet. Until it is, build and copy it from the repository root: ```bash npm run build @@ -46,8 +49,8 @@ This copies `main.js`, `manifest.json`, and `styles.css` into `/.obsidian ## Layout -- `src/discover.ts` — inventory path discovery (`chooseInventory`, `discoverInventory`). -- `src/model.ts` — pure view-model construction (`scopesModel`, `stripVM`, `headingLine`), tested without Obsidian. -- `src/load.ts` — loads the inventory via `@mozak/core` and refreshes stale `mozak.md` projections. -- `src/views.ts` — Obsidian `ItemView` for the scopes sidebar (`ScopesView`). -- `src/main.ts` — plugin lifecycle, file watchers, settings tab, and note navigation. +- `src/discover.ts`: inventory path discovery (`chooseInventory`, `discoverInventory`). +- `src/model.ts`: pure view-model construction (`scopesModel`, `stripVM`, `headingLine`), tested without Obsidian. +- `src/load.ts`: loads the inventory via `@mozak/core` and refreshes stale `mozak.md` projections. +- `src/views.ts`: Obsidian `ItemView` for the scopes sidebar (`ScopesView`). +- `src/main.ts`: plugin lifecycle, file watchers, settings tab, and note navigation. diff --git a/packages/obsidian/manifest.json b/packages/obsidian/manifest.json index f706a40..00dae19 100644 --- a/packages/obsidian/manifest.json +++ b/packages/obsidian/manifest.json @@ -1,7 +1,7 @@ { "id": "mozak", "name": "mozak", - "version": "0.4.8", + "version": "0.5.0", "minAppVersion": "1.14.4", "description": "Project scopes and plans shared with AI agents, stored as plain files.", "author": "pitfa19", diff --git a/packages/obsidian/package.json b/packages/obsidian/package.json index 0552332..a31d427 100644 --- a/packages/obsidian/package.json +++ b/packages/obsidian/package.json @@ -1,6 +1,6 @@ { "name": "@mozak/obsidian", - "version": "0.4.8", + "version": "0.5.0", "private": true, "type": "module", "description": "Read-only Obsidian plugin that lists every mozak scope and its plans.", @@ -10,7 +10,7 @@ "test": "node --import ../../scripts/test-git-isolation.mjs --test --experimental-strip-types test/*.test.ts" }, "dependencies": { - "@mozak/core": "0.4.8" + "@mozak/core": "0.5.0" }, "devDependencies": { "esbuild": "^0.28.0", diff --git a/packages/obsidian/src/load.ts b/packages/obsidian/src/load.ts index 9ced5dd..fe9fa7e 100644 --- a/packages/obsidian/src/load.ts +++ b/packages/obsidian/src/load.ts @@ -1,9 +1,9 @@ // Impure loader. Reuses core for parsing and validation: loadInventory, resolveScope, readScope, reviewRows // (the same functions behind `mozak scopes` and `mozak plans`). Reading never writes. The single write path, // renderStaleProjections, regenerates mozak.md through core and never touches mozak.json. -import { lstatSync, readdirSync, realpathSync } from "node:fs"; -import { join } from "node:path"; -import { DomainError, executeOperation, loadInventory, readRemoteMeta, readScope, resolveScope, reviewRows, SCOPE_FILE_NAMES } from "@mozak/core"; +import { lstatSync, readdirSync } from "node:fs"; +import { basename, join } from "node:path"; +import { annotationsEnabled, DomainError, executeOperation, focusChange, loadInventory, readAnnotations, readFocus, readRemoteMeta, readScope, resolveScope, reviewRows, SCOPE_FILE_NAMES } from "@mozak/core"; import { remoteVM, scopesModel, type ScopeLoad, type ScopesModel } from "./model.ts"; const ENTRY_NAMES = ["AGENTS.md", ...SCOPE_FILE_NAMES, "README.md"]; @@ -25,6 +25,7 @@ function fail(err: unknown): { code: string; message: string } { /** Throws a DomainError when the inventory itself is unreadable or invalid. Per-scope failures become rows. */ export function loadScopesModel(inventoryPath: string): ScopesModel { const inv = loadInventory(inventoryPath); + const focus = readFocus(inventoryPath); const loads: ScopeLoad[] = inv.scopes.map((entry) => { // Remote scopes are read from the local cache only. Refreshing the view never touches the network. const remote = entry.remote @@ -43,6 +44,10 @@ export function loadScopesModel(inventoryPath: string): ScopesModel { counts: { completed: groups.completed.length, open: groups.open.length, awaiting: groups.awaiting.length }, awaitingRows: groups.awaiting.map((r) => ({ planId: r.planId, rowKind: r.rowKind })), reviewNeededPlanIds: reviewNeeded, + // Owner annotations are display-only here, and read only for scopes that turn them on (off by default). + // A broken sidecar simply shows no refs; `mozak check` reports it. + annotations: annotationsEnabled(inv, resolved) ? readAnnotations(resolved.root, entry.id).doc : null, + focus: focus[entry.id] ?? [], ...(remote ? { remote } : {}), }; } catch (err) { @@ -54,6 +59,17 @@ export function loadScopesModel(inventoryPath: string): ScopesModel { export { fail as describeError }; +/** + * The star toggle: add or remove one plan in its scope's focus list through core's setFocus (inventory lock, validated + * atomic write). The plugin never writes plan state. Returns the new list, or the error for a notice. + */ +export function toggleFocus(inventoryPath: string, scope: string, plan: string, focused: boolean): { ok: true; focus: string[] } | { ok: false; code: string; message: string } { + const out = focusChange(inventoryPath, { scope, plan, action: focused ? "remove" : "add" }); + if (out.exitCode === 0) return { ok: true, focus: out.data.focus as string[] }; + const issue = (out.data.issues as { code: string; message: string }[])[0]!; + return { ok: false, code: issue.code, message: issue.message }; +} + /** * Regenerate stale mozak.md projections through core's render operation (the same code as `mozak render --all`). * The only write the plugin makes: mozak.md of local scopes, never mozak.json. Conflicts are reported, not overwritten. @@ -81,11 +97,43 @@ export function syncRemoteScopes(inventoryPath: string): { ok: boolean; message: return { ok: false, message: `${stale.length} of ${remote.length} could not sync (using cached copy): ${stale.map((r) => `${r.scope}: ${r.error ?? "failed"}`).join("; ")}` }; } -/** Resolve symlinks for vault-membership checks. A path that does not exist is returned unchanged. */ -export function realOrSelf(path: string): string { - try { - return realpathSync(path); - } catch { - return path; +interface LocalRow { repo: string | null; scopes: string[]; status: string; error?: string } +const LOCAL_OK = new Set(["fast-forwarded", "up-to-date", "ahead"]); + +/** + * The sync button: refresh remote scopes and fast-forward every git repo (vault) that holds a local scope, through + * core (the same code as `mozak sync --local`). Core takes the scope locks, merges only with --ff-only and never pushes, + * so a diverged vault is reported, not touched. Returns a one line summary. + */ +export function syncAll(inventoryPath: string): { ok: boolean; message: string } { + const inv = loadInventory(inventoryPath); + const out = executeOperation(inv, "sync", { local: true }, "agent"); + return { ok: out.exitCode === 0, message: syncSummary((out.data.remote ?? []) as { scope: string; stale: boolean; error?: string }[], (out.data.local ?? []) as LocalRow[]) }; +} + +/** One line for a sync notice. Pure, exported for tests. */ +export function syncSummary(remote: { scope: string; stale: boolean; error?: string }[], local: LocalRow[]): string { + const parts: string[] = []; + const name = (r: LocalRow) => (r.repo ? basename(r.repo) : r.scopes.join(", ")); + if (local.length > 0) { + const pulled = local.filter((r) => r.status === "fast-forwarded").length; + const ahead = local.filter((r) => r.status === "ahead"); + const okCount = local.filter((r) => LOCAL_OK.has(r.status)).length; + let s = `${okCount} of ${local.length} vault${local.length === 1 ? "" : "s"} synced`; + if (pulled) s += ` (${pulled} pulled)`; + if (ahead.length) s += `, ${ahead.map(name).join(", ")} ha${ahead.length === 1 ? "s" : "ve"} unpushed commits`; + parts.push(s); + const bad = local.filter((r) => !LOCAL_OK.has(r.status)); + if (bad.length) parts.push(`not synced: ${bad.map((r) => `${name(r)}: ${r.status === "not-fast-forward" ? "local and remote diverged, pull by hand" : r.error ?? r.status}`).join("; ")}`); + } + if (remote.length > 0) { + const stale = remote.filter((r) => r.stale); + parts.push(stale.length === 0 + ? `${remote.length} remote scope${remote.length === 1 ? "" : "s"} synced` + : `${stale.length} of ${remote.length} remote scopes could not sync (using cached copy): ${stale.map((r) => `${r.scope}: ${r.error ?? "failed"}`).join("; ")}`); } + return parts.length ? `${parts.join(". ")}.` : "Nothing to sync."; } + +/** Resolve symlinks for vault-membership checks. Shared with core. */ +export { realOrSelf } from "@mozak/core"; diff --git a/packages/obsidian/src/main.ts b/packages/obsidian/src/main.ts index 4f5dfc8..ce28c35 100644 --- a/packages/obsidian/src/main.ts +++ b/packages/obsidian/src/main.ts @@ -5,7 +5,7 @@ import { BRIDGE_FILE } from "@mozak/core"; import { chooseInventory } from "./discover.ts"; import { realOrSelf, renderStaleProjections, syncRemoteScopes } from "./load.ts"; import { startWatching, watchTargets } from "./watch.ts"; -import { headingLine, resolveOpenTarget, type PlanVM, type ScopeVM } from "./model.ts"; +import { headingLine, resolveOpenTarget, type PlanFilter, type PlanVM, type ScopeVM } from "./model.ts"; import { LEGACY_PLAN_VIEW_TYPE, ScopesView, SCOPES_VIEW_TYPE } from "./views.ts"; export interface MozakSettings { @@ -14,15 +14,17 @@ export interface MozakSettings { autoRefresh: boolean; /** Seconds between automatic syncs of remote (repo) scopes. 0 turns polling off. */ remotePollSeconds: number; + /** The sidebar tab last chosen. Null: Focus when it has plans, else Open. */ + lastFilter: PlanFilter | null; } -const DEFAULTS: MozakSettings = { inventoryPath: "", autoRefresh: true, remotePollSeconds: 60 }; +const DEFAULTS: MozakSettings = { inventoryPath: "", autoRefresh: true, remotePollSeconds: 60, lastFilter: null }; export default class MozakPlugin extends Plugin { - settings: MozakSettings = { ...DEFAULTS }; + override settings: MozakSettings = { ...DEFAULTS }; private stopWatch: (() => void) | null = null; private pollTimer: number | null = null; - async onload(): Promise { + override async onload(): Promise { this.settings = { ...DEFAULTS, ...((await this.loadData()) as Partial | null) }; this.registerView(SCOPES_VIEW_TYPE, (leaf) => new ScopesView(leaf, this)); this.addRibbonIcon("brain-circuit", "Open mozak scopes", () => void this.activateScopes()); @@ -35,7 +37,7 @@ export default class MozakPlugin extends Plugin { }); } - onunload(): void { this.stopAutoRefresh(); } + override onunload(): void { this.stopAutoRefresh(); } private stopAutoRefresh(): void { this.stopWatch?.(); @@ -177,7 +179,7 @@ class MozakSettingTab extends PluginSettingTab { // Declarative settings (Obsidian 1.13+, minAppVersion is 1.14.4) so they show up in settings search. // The default getControlValue/setControlValue read and write this.plugin.settings; setControlValue is // overridden to persist through saveSettings, which also restarts auto-refresh. - getSettingDefinitions(): SettingDefinitionItem[] { + override getSettingDefinitions(): SettingDefinitionItem[] { const resolved = this.plugin.inventory(); return [ { @@ -204,7 +206,7 @@ class MozakSettingTab extends PluginSettingTab { ]; } - async setControlValue(key: string, value: unknown): Promise { + override async setControlValue(key: string, value: unknown): Promise { const s = this.plugin.settings; if (key === "inventoryPath" && typeof value === "string") s.inventoryPath = value; else if (key === "autoRefresh" && typeof value === "boolean") s.autoRefresh = value; diff --git a/packages/obsidian/src/model.ts b/packages/obsidian/src/model.ts index e428cd2..9c3d8ca 100644 --- a/packages/obsidian/src/model.ts +++ b/packages/obsidian/src/model.ts @@ -1,12 +1,25 @@ // Pure view models. Turns core ScopeState plus review rows into plain data for the UI. No IO. // Plans are read in mozak.md, so the sidebar only needs identity, state, progress and a heading to jump to. -import { completedPlanLine, isBridgeFileName, planDisplayState, planHeading, planRoadmap, type Plan, type PlanDisplayState, type ScopeState } from "@mozak/core"; +import { completedPlanLine, isBridgeFileName, planDisplayState, planHeading, planRoadmap, resolveRef, type AnnotationsDoc, type Plan, type PlanDisplayState, type ScopeLookup, type ScopeState } from "@mozak/core"; export type PlanStateKey = PlanDisplayState; export type StopKey = "done" | "evidence" | "current" | "todo"; /** One sidebar segment per outcome, in roadmap order. */ export interface StripVM { stops: { key: StopKey; label: string }[]; done: number; total: number } +/** One cross-plan reference from owner annotations, seen from one plan. */ +export interface RefVM { + direction: "out" | "in"; + relation: "needs" | "informs" | "supersedes"; + /** Short reading: "needs", "needed by", "informs", "informed by", "supersedes", "superseded by". */ + verb: string; + /** The other plan as scope/plan[#outcome]. */ + other: string; + /** Title of the other plan when it resolves, else the raw target. */ + label: string; + status: "resolved" | "dangling" | "unavailable" | "pruned"; + evidence: string; +} export interface PlanVM { scopeId: string; id: string; @@ -24,6 +37,10 @@ export interface PlanVM { strip: StripVM | null; /** Exact heading or collapsed completed-plan line in mozak.md. */ heading: string; + /** Owner annotation refs from this plan and to it. Present only when there is at least one. */ + refs?: RefVM[]; + /** The owner starred this plan: its id is in the scope's inventory `focus` list. */ + focused: boolean; } export interface RemoteVM { spec: string; @@ -74,6 +91,10 @@ export interface ScopeLoad { reviewNeededPlanIds?: string[]; remote?: RemoteVM; error?: { code: string; message: string }; + /** Parsed mozak.annotations.json, when the scope has a valid one. */ + annotations?: AnnotationsDoc | null; + /** Plan ids from this scope's inventory `focus` list. Ids that are not plans are ignored. */ + focus?: string[]; } const STATE_LABEL: Record = { @@ -115,6 +136,7 @@ export function planViewModel( awaitingRows: { planId: string; rowKind: string }[] = [], reviewNeeded = false, scopeState?: ScopeState, + focused = false, ): PlanVM { const state = planState(plan); const shown = plan.accepted ?? plan.pending; @@ -146,6 +168,7 @@ export function planViewModel( reason, strip: scopeState ? stripVM(scopeState, plan) : null, heading: state === "completed" ? completedPlanLine(plan) : planHeading(plan), + focused, }; } @@ -170,8 +193,9 @@ export function scopeViewModel(load: ScopeLoad): ScopeVM { }; } const needed = new Set(load.reviewNeededPlanIds ?? []); + const focus = new Set(load.focus ?? []); const plans = load.state.plans - .map((p) => planViewModel(load.id, p, load.awaitingRows ?? [], needed.has(p.id), load.state)) + .map((p) => planViewModel(load.id, p, load.awaitingRows ?? [], needed.has(p.id), load.state, focus.has(p.id))) .sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state] || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0)); return { id: load.id, @@ -190,8 +214,44 @@ export function scopeViewModel(load: ScopeLoad): ScopeVM { }; } +const VERB: Record = { needs: ["needs", "needed by"], informs: ["informs", "informed by"], supersedes: ["supersedes", "superseded by"] }; + +/** + * Attach owner annotation refs to plan view models, both directions, across every loaded scope. Pure: resolution + * uses only the states already loaded. A scope that failed to load makes its targets "unavailable". + */ +export function attachRefs(loads: ScopeLoad[], scopes: ScopeVM[]): void { + const lookup: ScopeLookup = (id) => { + const load = loads.find((l) => l.id === id); + if (!load) return "unknown"; + return load.state && !load.error ? load.state : "unavailable"; + }; + const plans = new Map(); + for (const s of scopes) for (const p of s.plans) plans.set(`${s.id}/${p.id}`, p); + const add = (key: string, ref: RefVM) => { + const vm = plans.get(key); + if (vm) vm.refs = [...(vm.refs ?? []), ref]; + }; + for (const load of loads) { + const doc = load.state && !load.error ? load.annotations : null; + if (!doc) continue; + for (const planId of Object.keys(doc.plans).sort()) { + for (const r of doc.plans[planId]!.refs) { + const res = resolveRef(r.target, lookup); + const to = res.status === "resolved" ? `${res.scope}/${res.planId}` : null; + const from = `${load.id}/${planId}`; + add(from, { direction: "out", relation: r.relation, verb: VERB[r.relation][0], other: r.target, label: to ? plans.get(to)?.title ?? r.target : r.target, status: res.status, evidence: r.evidence }); + if (to) add(to, { direction: "in", relation: r.relation, verb: VERB[r.relation][1], other: from, label: plans.get(from)?.title ?? from, status: "resolved", evidence: r.evidence }); + } + } + } + // Outgoing first, then incoming; within each, the order the owner recorded them per scope. + for (const vm of plans.values()) if (vm.refs) vm.refs = [...vm.refs.filter((r) => r.direction === "out"), ...vm.refs.filter((r) => r.direction === "in")]; +} + export function scopesModel(inventoryPath: string, loads: ScopeLoad[], now = new Date()): ScopesModel { const scopes = loads.map(scopeViewModel); + attachRefs(loads, scopes); const totals = { completed: 0, open: 0, awaiting: 0, scopes: scopes.length, failed: 0 }; for (const s of scopes) { if (s.status === "failed") totals.failed++; @@ -211,13 +271,29 @@ export function countsSummary(c: ScopeCounts): string { return parts.length ? parts.join(", ") : "no plans"; } -export type PlanFilter = "all" | "open" | "completed"; +export type PlanFilter = "open" | "focus" | "completed"; -/** Open means still in play: open, awaiting approval, or paused. Rejected plans only show under All. */ -export function planMatches(plan: Pick, filter: PlanFilter): boolean { - if (filter === "all") return true; +/** The sidebar tabs, in order. There is no All tab: rejected plans show in no tab (`mozak plans --include-rejected`). */ +export const FILTERS: readonly { id: PlanFilter; label: string; tip: string }[] = [ + { id: "open", label: "Open", tip: "Open, awaiting approval or paused" }, + { id: "focus", label: "Focus", tip: "Starred plans that are still open" }, + { id: "completed", label: "Done", tip: "Completed plans" }, +]; + +/** + * Open means still in play: open, awaiting approval, or paused. Focus is a starred plan still in play, so a focused + * plan that completes shows only under Done. + */ +export function planMatches(plan: Pick, filter: PlanFilter): boolean { if (filter === "completed") return plan.state === "completed"; - return plan.state === "open" || plan.state === "awaiting" || plan.state === "paused"; + const inPlay = plan.state === "open" || plan.state === "awaiting" || plan.state === "paused"; + return filter === "focus" ? inPlay && plan.focused : inPlay; +} + +/** The tab to show: the remembered one when it still exists, else Focus when it has plans, else Open. */ +export function defaultFilter(plans: Pick[], remembered: PlanFilter | null): PlanFilter { + if (remembered && FILTERS.some((f) => f.id === remembered)) return remembered; + return plans.some((p) => planMatches(p, "focus")) ? "focus" : "open"; } /** Staleness of a remote scope's cached copy without touching the network. Mirrors core's ten minute window. */ diff --git a/packages/obsidian/src/views.ts b/packages/obsidian/src/views.ts index 17dbdd6..a6b1bd9 100644 --- a/packages/obsidian/src/views.ts +++ b/packages/obsidian/src/views.ts @@ -1,6 +1,6 @@ import { ItemView, Notice, setIcon, type WorkspaceLeaf } from "obsidian"; -import { countRemote, planMatches, scopesModel, type PlanFilter, type ScopeVM, type ScopesModel, type StripVM } from "./model.ts"; -import { loadScopesModel, describeError, syncRemoteScopes } from "./load.ts"; +import { countRemote, defaultFilter, FILTERS, planMatches, scopesModel, type PlanFilter, type PlanVM, type RefVM, type ScopeVM, type ScopesModel, type StripVM } from "./model.ts"; +import { loadScopesModel, describeError, syncAll, toggleFocus } from "./load.ts"; import type MozakPlugin from "./main.ts"; import { cachedUpdateNotice } from "@mozak/core"; @@ -14,11 +14,7 @@ function el(parent: HTMLElement, tag: string, cls?: string, text?: string): HTML return e; } -const FILTERS: { id: PlanFilter; label: string; tip: string }[] = [ - { id: "all", label: "All", tip: "All plans" }, - { id: "open", label: "Open", tip: "Open, awaiting approval or paused" }, - { id: "completed", label: "Done", tip: "Completed plans" }, -]; +const EMPTY: Record = { open: "No open plans. Nice.", focus: "Star a plan to focus on it", completed: "No completed plans yet." }; /** "github:owner/repo" or an https URL to a browsable GitHub URL. Null for file:// remotes. */ function repoUrl(spec: string): string | null { @@ -49,17 +45,17 @@ function rank(s: ScopeVM): number { export class ScopesView extends ItemView { private model: ScopesModel | null = null; private error: string | null = null; - private expanded = new Set(); private collapsed = new Set(); - private filter: PlanFilter = "all"; + /** Null until the first model loads; then the remembered tab, else Focus when it has plans, else Open. */ + private filter: PlanFilter | null = null; private plugin: MozakPlugin; constructor(leaf: WorkspaceLeaf, plugin: MozakPlugin) { super(leaf); this.plugin = plugin; } getViewType() { return SCOPES_VIEW_TYPE; } getDisplayText() { return "mozak scopes"; } - getIcon() { return "brain-circuit"; } + override getIcon() { return "brain-circuit"; } - async onOpen(): Promise { this.refresh(); } + override async onOpen(): Promise { this.refresh(); } refresh(): void { const choice = this.plugin.inventory(); @@ -75,9 +71,27 @@ export class ScopesView extends ItemView { this.error = `${d.message} (${d.code})`; } } + if (this.model && this.filter === null) this.filter = defaultFilter(this.model.scopes.flatMap((s) => s.plans), this.plugin.settings.lastFilter); this.render(); } + /** Remember the tab across restarts in the plugin settings. */ + private setFilter(filter: PlanFilter): void { + this.filter = filter; + this.plugin.settings.lastFilter = filter; + void this.plugin.saveSettings(); + this.render(); + } + + /** Star or unstar one plan through core's setFocus, then reload so every tab sees it. */ + private toggleStar(scope: ScopeVM, plan: PlanVM): void { + const path = this.plugin.inventory().path; + if (!path) return; + const out = toggleFocus(path, scope.id, plan.id, plan.focused); + if (!out.ok) new Notice(`mozak: could not ${plan.focused ? "unstar" : "star"} ${plan.title}: ${out.message}`, 10000); + this.refresh(); + } + private syncRemote(button: HTMLElement): void { const path = this.plugin.inventory().path; if (!path) return; @@ -86,7 +100,7 @@ export class ScopesView extends ItemView { // Let the label paint before the synchronous core call blocks the UI thread. window.setTimeout(() => { try { - const result = syncRemoteScopes(path); + const result = syncAll(path); new Notice(`mozak: ${result.message}`, result.ok ? 4000 : 10000); } catch (err) { const d = describeError(err); @@ -100,14 +114,15 @@ export class ScopesView extends ItemView { const root = this.contentEl; root.empty(); root.addClass("mozak-root"); + const filter = this.filter ?? "open"; const head = el(root, "div", "mozak-header"); const title = el(head, "span", "mozak-title"); - setIcon(el(title, "span", `mozak-title-icon icon-${this.filter}`), this.getIcon()); + setIcon(el(title, "span", `mozak-title-icon icon-${filter}`), this.getIcon()); el(title, "span", undefined, "mozak"); const tools = el(head, "div", "mozak-tools"); - if (this.model && countRemote(this.model.scopes).remote > 0) { + if (this.model && this.model.scopes.length > 0) { const sync = el(tools, "button", "clickable-icon mozak-sync"); - sync.setAttr("aria-label", "Sync remote scopes"); + sync.setAttr("aria-label", "Sync vaults and repos"); setIcon(sync, "cloud-download"); sync.addEventListener("click", () => this.syncRemote(sync)); } @@ -133,12 +148,9 @@ export class ScopesView extends ItemView { el(root, "div", "mozak-warn", [m.totals.failed ? `${m.totals.failed} unreadable` : "", stale ? `${stale} remote stale` : ""].filter(Boolean).join(", ")); } - const visible = (this.filter === "all" - ? [...m.scopes] - : m.scopes.filter((s) => s.plans.some((p) => planMatches(p, this.filter)))) - .sort((a, b) => rank(a) - rank(b)); + const visible = m.scopes.filter((s) => s.plans.some((p) => planMatches(p, filter))).sort((a, b) => rank(a) - rank(b)); if (visible.length === 0) { - el(root, "div", "mozak-muted mozak-none", this.filter === "open" ? "No open plans. Nice." : "No completed plans yet."); + el(root, "div", "mozak-muted mozak-none", EMPTY[filter]); return; } const list = el(root, "div", "mozak-list-scopes"); @@ -166,14 +178,14 @@ export class ScopesView extends ItemView { pill.setAttr("aria-label", f.tip); el(pill, "span", "mozak-pill-label", f.label); el(pill, "span", "mozak-pill-count", String(n)); - pill.addEventListener("click", () => { this.filter = f.id; this.render(); }); + pill.addEventListener("click", () => this.setFilter(f.id)); } } private renderScope(parent: HTMLElement, scope: ScopeVM): void { - // A filter only shows scopes with matching plans, so open them to show those plans directly. - const filtered = this.filter !== "all"; - const open = filtered ? !this.collapsed.has(scope.id) : this.expanded.has(scope.id); + // Every tab only shows scopes with matching plans, so they start open to show those plans directly. + const filter = this.filter ?? "open"; + const open = !this.collapsed.has(scope.id); const openN = scope.plans.filter((p) => planMatches(p, "open")).length; const doneN = scope.plans.filter((p) => planMatches(p, "completed")).length; const empty = scope.status === "ok" && scope.plans.length === 0; @@ -210,9 +222,7 @@ export class ScopesView extends ItemView { md.addEventListener("click", (ev) => { ev.stopPropagation(); void this.plugin.openMozakMd(scope); }); } row.addEventListener("click", () => { - const set = filtered ? this.collapsed : this.expanded; - const add = filtered ? open : !open; - if (add) set.add(scope.id); else set.delete(scope.id); + if (open) this.collapsed.add(scope.id); else this.collapsed.delete(scope.id); this.render(); }); if (!open) return; @@ -237,9 +247,15 @@ export class ScopesView extends ItemView { } if (scope.status === "failed") el(body, "div", "mozak-error", `${scope.errorCode}: ${scope.errorMessage}`); if (empty) el(body, "div", "mozak-muted mozak-noplans", "No plans yet"); - for (const plan of scope.plans.filter((p) => planMatches(p, this.filter))) { + for (const plan of scope.plans.filter((p) => planMatches(p, filter))) { const p = el(body, "div", `mozak-plan-row row-${plan.state}`); p.setAttr("title", `${plan.stateLabel}: ${plan.title}${plan.strip ? `\n${plan.strip.done}/${plan.strip.total} outcomes done` : ""}\nOpen in ${scope.bridgeFile ?? "mozak.md"}`); + const star = el(p, "span", `clickable-icon mozak-star${plan.focused ? " is-focused" : ""}`); + setIcon(star, "star"); + star.setAttr("aria-label", plan.focused ? "Remove from Focus" : "Add to Focus"); + star.setAttr("aria-pressed", String(plan.focused)); + // The star only edits the focus list; the row click still opens the plan. + star.addEventListener("click", (ev) => { ev.stopPropagation(); this.toggleStar(scope, plan); }); el(p, "span", `mozak-dot dot-${plan.state}`); el(p, "span", "mozak-plan-title", plan.title); if (plan.state === "awaiting" || plan.state === "paused" || plan.state === "rejected") { @@ -248,10 +264,20 @@ export class ScopesView extends ItemView { renderStrip(p, plan.strip); } p.addEventListener("click", () => void this.plugin.openPlan(scope, plan)); + if (plan.refs?.length) renderRefs(body, plan.refs); } } } +/** Incoming and outgoing owner annotation refs under a plan row. Display only; annotations change only by `mozak annotate`. */ +function renderRefs(parent: HTMLElement, refs: RefVM[]): void { + const box = el(parent, "div", "mozak-plan-refs"); + for (const ref of refs) { + const item = el(box, "span", `mozak-ref ref-${ref.direction} ref-${ref.status}`, `${ref.direction === "out" ? "→" : "←"} ${ref.verb} ${ref.label}${ref.status === "resolved" ? "" : ` (${ref.status})`}`); + item.setAttr("title", `${ref.other}\n${ref.evidence}`); + } +} + /** One segment per outcome (done green, evidence gold, current purple, todo faint), then done/total. Display only. */ function renderStrip(parent: HTMLElement, strip: StripVM): void { const s = el(parent, "span", "mozak-strip"); diff --git a/packages/obsidian/styles.css b/packages/obsidian/styles.css index 6641212..9b3b3ec 100644 --- a/packages/obsidian/styles.css +++ b/packages/obsidian/styles.css @@ -1,4 +1,4 @@ -/* ---------- Palette: All gold, Open purple, Done green ---------- */ +/* ---------- Palette: Open purple, Focus gold, Done green ---------- */ .mozak-root { --mozak-gold: #d4a017; --mozak-purple: #8b5cf6; @@ -37,6 +37,7 @@ transition: background 100ms ease, color 100ms ease; } .mozak-pill.pill-open { --pill: var(--mozak-purple); } +.mozak-pill.pill-focus { --pill: var(--mozak-gold); } .mozak-pill.pill-completed { --pill: var(--mozak-green); } .mozak-pill:hover { color: var(--pill); background: color-mix(in srgb, var(--pill) 12%, transparent); } .mozak-pill.is-active { background: var(--pill); color: #fff; } @@ -102,6 +103,13 @@ .mozak-dot.dot-open, .mozak-dot.dot-awaiting, .mozak-dot.dot-paused { background: var(--mozak-purple); } .mozak-dot.dot-completed { background: var(--mozak-green); } .mozak-dot.dot-rejected { background: var(--text-error); } +/* Star toggle: faint until hovered or set; gold and filled when the plan is in Focus. */ +.mozak-star { display: flex; flex: none; padding: 1px; color: var(--text-faint); opacity: 0; transition: opacity 100ms ease, color 100ms ease; } +.mozak-plan-row:hover .mozak-star, .mozak-star:focus-visible, .mozak-star.is-focused { opacity: 1; } +.mozak-star:hover { color: var(--mozak-gold); } +.mozak-star.is-focused { color: var(--mozak-gold); } +.mozak-star.is-focused svg { fill: currentColor; } +.mozak-star svg { width: 12px; height: 12px; } .mozak-plan-row.row-completed .mozak-plan-title { color: var(--text-faint); } .mozak-mini { flex: none; font-size: 10px; padding: 0 5px; border-radius: 4px; text-transform: lowercase; color: var(--text-muted); background: var(--background-modifier-border); } .mozak-mini.state-awaiting { color: var(--mozak-purple); background: color-mix(in srgb, var(--mozak-purple) 16%, transparent); } @@ -117,3 +125,5 @@ .mozak-strip-count { font-size: 10px; font-variant-numeric: tabular-nums; color: var(--text-faint); } .mozak-sync.is-busy svg { animation: mozak-spin 0.9s linear infinite; } @keyframes mozak-spin { to { transform: rotate(360deg); } } +.mozak-plan-refs { display: flex; flex-wrap: wrap; gap: 2px 8px; margin: -2px 0 4px 18px; font-size: 10px; color: var(--text-muted); } +.mozak-ref.ref-dangling, .mozak-ref.ref-unavailable { color: var(--text-error); } diff --git a/packages/obsidian/test/focus.test.ts b/packages/obsidian/test/focus.test.ts new file mode 100644 index 0000000..8be6894 --- /dev/null +++ b/packages/obsidian/test/focus.test.ts @@ -0,0 +1,41 @@ +// The sidebar Focus tab and star toggle, through the real loader and core. Synthetic temp folders only. +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { loadScopesModel, toggleFocus } from "../src/load.ts"; +import { planMatches } from "../src/model.ts"; +import { cleanup, world } from "../../core/test/annotations-fixture.ts"; + +after(cleanup); + +test("the star adds and removes a plan in Focus through the inventory only; plan files never change", () => { + const w = world(["alpha"]); + w.propose("alpha", "a1"); w.propose("alpha", "a2"); + const before = w.bytes("alpha"); + const focused = () => loadScopesModel(w.config).scopes[0]!.plans.filter((p) => planMatches(p, "focus")).map((p) => p.id); + assert.deepEqual(focused(), []); + assert.deepEqual(toggleFocus(w.config, "alpha", "a2", false), { ok: true, focus: ["a2"] }); + assert.deepEqual(focused(), ["a2"]); + assert.deepEqual(JSON.parse(readFileSync(w.config, "utf8")).scopes[0].focus, ["a2"]); + assert.deepEqual(toggleFocus(w.config, "alpha", "a2", true), { ok: true, focus: [] }); + assert.deepEqual(focused(), []); + assert.deepEqual(w.bytes("alpha"), before); +}); + +test("a failed star reports the reason and leaves the inventory unchanged", () => { + const w = world(["alpha"]); + const text = readFileSync(w.config, "utf8"); + const out = toggleFocus(w.config, "alpha", "missing", false); + assert.equal(out.ok, false); + assert.equal(out.ok === false && out.code, "plan-not-found"); + assert.equal(readFileSync(w.config, "utf8"), text); +}); + +test("the view has no All tab, a star on every plan row, and the Focus empty message", () => { + const src = readFileSync(new URL("../src/views.ts", import.meta.url), "utf8"); + assert.doesNotMatch(src, /"all"/); + assert.match(src, /mozak-star/); + assert.match(src, /ev\.stopPropagation\(\); this\.toggleStar\(scope, plan\)/, "the star stops the row click that opens the plan"); + assert.match(src, /Star a plan to focus on it/); + assert.match(src, /lastFilter = filter/, "the last tab is remembered in plugin settings"); +}); diff --git a/packages/obsidian/test/model.test.ts b/packages/obsidian/test/model.test.ts index 8237d89..945f0ee 100644 --- a/packages/obsidian/test/model.test.ts +++ b/packages/obsidian/test/model.test.ts @@ -7,15 +7,39 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { applyMutation, executeOperation, initScopeState, loadInventory, mutateScope, planDisplayState, readScope, renderBridge, renderBridgeLegacy, reviewShow } from "@mozak/core"; import { chooseInventory, discoverInventory } from "../src/discover.ts"; -import { countRemote, countsSummary, headingLine, planMatches, planState, remoteVM, resolveOpenTarget, scopesModel, scopeViewModel, stripVM } from "../src/model.ts"; +import { countRemote, countsSummary, defaultFilter, FILTERS, headingLine, planMatches, planState, remoteVM, resolveOpenTarget, scopesModel, scopeViewModel, stripVM, type PlanFilter, type PlanVM } from "../src/model.ts"; import { loadScopesModel, realOrSelf, renderStaleProjections } from "../src/load.ts"; +import { cleanup as cleanupWorlds, world } from "../../core/test/annotations-fixture.ts"; +import { after } from "node:test"; -test("planMatches: all shows every state, open groups in-play states, completed is exact", () => { +after(cleanupWorlds); + +test("planMatches: open groups in-play states, focus is focused and in play, completed is exact, rejected is in no tab", () => { const states = ["open", "awaiting", "paused", "completed", "rejected"] as const; - const pick = (f: "all" | "open" | "completed") => states.filter((s) => planMatches({ state: s }, f)); - assert.deepEqual(pick("all"), [...states]); - assert.deepEqual(pick("open"), ["open", "awaiting", "paused"]); - assert.deepEqual(pick("completed"), ["completed"]); + const pick = (f: PlanFilter, focused: boolean) => states.filter((s) => planMatches({ state: s, focused }, f)); + assert.deepEqual(pick("open", false), ["open", "awaiting", "paused"]); + assert.deepEqual(pick("open", true), ["open", "awaiting", "paused"]); + assert.deepEqual(pick("focus", false), []); + assert.deepEqual(pick("focus", true), ["open", "awaiting", "paused"], "a focused plan that completes shows only under Done"); + assert.deepEqual(pick("completed", true), ["completed"]); + assert.deepEqual(FILTERS.map((f) => [f.id, f.label]), [["open", "Open"], ["focus", "Focus"], ["completed", "Done"]]); +}); + +test("defaultFilter: Focus when it has plans, else Open; a remembered tab wins", () => { + const plan = (state: PlanVM["state"], focused: boolean) => ({ state, focused }); + assert.equal(defaultFilter([plan("open", false)], null), "open"); + assert.equal(defaultFilter([plan("open", true)], null), "focus"); + assert.equal(defaultFilter([plan("completed", true)], null), "open", "a completed focused plan does not make Focus the default"); + assert.equal(defaultFilter([plan("open", true)], "completed"), "completed"); + assert.equal(defaultFilter([plan("open", true)], "all" as PlanFilter), "focus", "the retired All tab falls back to the rule"); +}); + +test("scopesModel marks plans the inventory focus list names", () => { + const w = world(["alpha"]); + w.propose("alpha", "a"); w.propose("alpha", "b"); + const state = readScope(w.entries.alpha).state; + const m = scopesModel("/inv.json", [{ id: "alpha", root: w.entries.alpha.root, entryFiles: [], state, focus: ["b", "gone"] }]); + assert.deepEqual(m.scopes[0]!.plans.map((p) => [p.id, p.focused]), [["a", false], ["b", true]]); }); test("sidebar plan state is core's display state, one rule for mozak.md and the sidebar", () => { diff --git a/packages/obsidian/test/refs.test.ts b/packages/obsidian/test/refs.test.ts new file mode 100644 index 0000000..1b525c6 --- /dev/null +++ b/packages/obsidian/test/refs.test.ts @@ -0,0 +1,32 @@ +import { after, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { loadScopesModel } from "../src/load.ts"; +import { cleanup, world } from "../../core/test/annotations-fixture.ts"; + +after(cleanup); + +test("plugin model shows outgoing and incoming owner refs, including across scopes and dangling targets", () => { + const w = world(["alpha", "beta"], { annotations: true }); + w.propose("alpha", "a", { title: "Synthetic alpha A" }); + w.propose("alpha", "b", { title: "Synthetic alpha B" }); + w.propose("beta", "c", { title: "Synthetic beta C" }); + w.propose("alpha", "gone"); + assert.equal(w.annotate("alpha", [ + { kind: "ref", planId: "a", target: "alpha/b", relation: "needs", evidence: "A needs B." }, + { kind: "ref", planId: "a", target: "beta/c", relation: "informs", evidence: "A informs C." }, + { kind: "ref", planId: "b", target: "alpha/gone", relation: "supersedes", evidence: "B replaces gone." }, + ]).exitCode, 0); + const path = join(w.entries.alpha.root, "mozak.json"); + const state = JSON.parse(readFileSync(path, "utf8")); + state.plans = state.plans.filter((p: { id: string }) => p.id !== "gone"); + writeFileSync(path, JSON.stringify(state, null, 2) + "\n"); + const model = loadScopesModel(w.config); + const plan = (scope: string, id: string) => model.scopes.find((s) => s.id === scope)!.plans.find((p) => p.id === id)!; + const show = (scope: string, id: string) => (plan(scope, id).refs ?? []).map((r) => `${r.direction} ${r.verb} ${r.label} ${r.status}`); + assert.deepEqual(show("alpha", "a"), ["out needs Synthetic alpha B resolved", "out informs Synthetic beta C resolved"]); + assert.deepEqual(show("alpha", "b"), ["out supersedes alpha/gone dangling", "in needed by Synthetic alpha A resolved"]); + assert.deepEqual(show("beta", "c"), ["in informed by Synthetic alpha A resolved"]); +}); + diff --git a/packages/obsidian/test/submission.test.ts b/packages/obsidian/test/submission.test.ts new file mode 100644 index 0000000..a05bc36 --- /dev/null +++ b/packages/obsidian/test/submission.test.ts @@ -0,0 +1,26 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; + +const readRepo = (p: string) => readFileSync(new URL(`../../../${p}`, import.meta.url), "utf8"); + +// Obsidian reads manifest.json and versions.json from the default branch. versions.json maps a plugin version to +// the lowest Obsidian version it needs, so older apps can fall back to a compatible release. +test("versions.json maps the current plugin version to the manifest's minAppVersion", () => { + const manifest = JSON.parse(readRepo("manifest.json")) as { version: string; minAppVersion: string; description: string; id: string }; + const versions = JSON.parse(readRepo("versions.json")) as Record; + assert.equal(versions[manifest.version], manifest.minAppVersion); + for (const [v, min] of Object.entries(versions)) { + assert.match(v, /^\d+\.\d+\.\d+$/, `plugin version ${v} is x.y.z`); + assert.match(min, /^\d+\.\d+\.\d+$/, `minAppVersion ${min} is x.y.z`); + } + assert.ok(!manifest.id.includes("obsidian"), "id does not contain obsidian"); + assert.ok(manifest.description.length <= 250 && manifest.description.endsWith("."), "description is short and ends with a period"); +}); + +test("plugin README discloses the visibility check and that the update notice reads a cache only", () => { + const readme = readRepo("packages/obsidian/README.md"); + assert.match(readme, /api\.github\.com\/repos\/OWNER\/REPO/); + assert.match(readme, /makes no network call for this/); + assert.match(readme, /never installs or updates itself/); +}); diff --git a/packages/obsidian/test/sync.test.ts b/packages/obsidian/test/sync.test.ts new file mode 100644 index 0000000..b4d6b34 --- /dev/null +++ b/packages/obsidian/test/sync.test.ts @@ -0,0 +1,52 @@ +// The sidebar sync button: remote scopes plus a fast-forward of every vault repo that holds a local scope. +// Local bare repos in temp dirs only, never GitHub. +import { test, after } from "node:test"; +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { initScopeState } from "@mozak/core"; +import { syncAll, syncSummary } from "../src/load.ts"; + +const scratch = process.env.JCODE_SCRATCH_DIR ?? process.env.TMPDIR ?? tmpdir(); +const made: string[] = []; +after(() => { for (const d of made) { if (!d.includes("/mozak-obs-sync-")) throw new Error(d); rmSync(d, { recursive: true, force: true }); } }); +const g = (cwd: string, ...args: string[]) => + execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", "-c", "protocol.file.allow=always", ...args], { cwd, encoding: "utf8", env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }).trim(); + +test("syncSummary names pulled, ahead and diverged vaults and stale remotes", () => { + assert.equal(syncSummary([], []), "Nothing to sync."); + assert.equal(syncSummary([], [{ repo: "/v/obsidian", scopes: ["a"], status: "fast-forwarded" }, { repo: "/v/anpit", scopes: ["b"], status: "up-to-date" }]), "2 of 2 vaults synced (1 pulled)."); + assert.equal(syncSummary([], [{ repo: "/v/anpit", scopes: ["b"], status: "ahead" }]), "1 of 1 vault synced, anpit has unpushed commits."); + assert.equal( + syncSummary([{ scope: "r", stale: true, error: "offline" }, { scope: "s", stale: false }], [{ repo: "/v/obsidian", scopes: ["a"], status: "not-fast-forward" }]), + "0 of 1 vault synced. not synced: obsidian: local and remote diverged, pull by hand. 1 of 2 remote scopes could not sync (using cached copy): r: offline.", + ); +}); + +test("syncAll fast-forwards a vault repo that holds a local scope", () => { + const base = mkdtempSync(join(scratch, "mozak-obs-sync-")); + made.push(base); + const bare = join(base, "vault.git"); + const seed = join(base, "seed"); + g(base, "init", "--bare", "-b", "main", bare); + mkdirSync(join(seed, "notes", "s1"), { recursive: true }); + g(seed, "init", "-b", "main"); + writeFileSync(join(seed, "notes", "s1", "README.md"), "# r\n"); + writeFileSync(join(seed, "notes", "s1", "AGENTS.md"), "# a\n"); + initScopeState({ id: "s1", root: join(seed, "notes", "s1") }, { operationId: "init-s1", scopeId: "s1", kind: "project", title: "s1", expectedAbsent: { graph: true, bridge: true }, ownerRef: "host:t", ownerMessageAt: "2026-10-12T08:50:00.000Z" }); + g(seed, "add", "."); g(seed, "commit", "-q", "-m", "seed"); g(seed, "remote", "add", "origin", bare); g(seed, "push", "-q", "-u", "origin", "main"); + const mine = join(base, "mine"); + g(base, "clone", "-q", bare, mine); + const inv = join(base, "inventory.json"); + writeFileSync(inv, JSON.stringify({ format: "mozak.local/v3", scopes: [{ id: "s1", root: join(mine, "notes", "s1") }] })); + // Another machine pushes a note. + writeFileSync(join(seed, "new-note.md"), "from another machine\n"); + g(seed, "add", "."); g(seed, "commit", "-q", "-m", "note"); g(seed, "push", "-q"); + const first = syncAll(inv); + assert.equal(first.ok, true, first.message); + assert.equal(first.message, "1 of 1 vault synced (1 pulled)."); + assert.equal(g(mine, "rev-parse", "HEAD"), g(seed, "rev-parse", "HEAD")); + assert.deepEqual(syncAll(inv), { ok: true, message: "1 of 1 vault synced." }); +}); diff --git a/scripts/build-demo-preview.mjs b/scripts/build-demo-preview.mjs new file mode 100644 index 0000000..852d04c --- /dev/null +++ b/scripts/build-demo-preview.mjs @@ -0,0 +1,15 @@ +// Extract a sharp README still from the existing public demo. No network or uploads. +// Usage: node scripts/build-demo-preview.mjs SOURCE.mp4 OUTPUT.png +import { execFileSync } from 'node:child_process'; +import fs from 'node:fs'; +import path from 'node:path'; +const [source, output] = process.argv.slice(2); +if (!source || !output || !output.endsWith('.png')) throw new Error('usage: node scripts/build-demo-preview.mjs SOURCE.mp4 OUTPUT.png'); +if (fs.existsSync(output)) throw new Error('output exists; choose a new file name'); +const probe = JSON.parse(execFileSync('ffprobe', ['-v','error','-show_entries','format=duration','-of','json',source], { encoding:'utf8',timeout:30000 })); +if (!(Number(probe.format?.duration) >= 62)) throw new Error('source must be the full demo, at least 62 seconds'); +fs.mkdirSync(path.dirname(path.resolve(output)), { recursive:true }); +execFileSync('ffmpeg', ['-hide_banner','-loglevel','error','-ss','60','-i',source,'-frames:v','1','-vf','scale=1600:-2:flags=lanczos','-compression_level','9',output], { stdio:'inherit',timeout:60000 }); +const bytes=fs.statSync(output).size; +if (bytes >= 400000) throw new Error('preview exceeds 400 KB; inspect it before use'); +console.log(JSON.stringify({sourceSecond:60,width:1600,bytes,preview:'still',note:'Visually inspect readability. The full demo remains linked.'},null,2)); diff --git a/scripts/check-links.mjs b/scripts/check-links.mjs new file mode 100644 index 0000000..0372a1f --- /dev/null +++ b/scripts/check-links.mjs @@ -0,0 +1,125 @@ +#!/usr/bin/env node +// Checks relative links in the repo's Markdown files: the target file must exist, and a `#anchor` +// into a Markdown file must match one of its headings (GitHub slug rules) or an HTML id. +// External links (http, https, mailto) are not fetched. Links inside code blocks and inline code are skipped. +// Run: node scripts/check-links.mjs [--json]. Exit 0 when every link resolves, 1 when any is broken. +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; + +const SKIP_DIRS = new Set(["node_modules", "dist", ".git", "scratch", ".mozak-cache"]); + +/** Markdown files to check: tracked and untracked-but-not-ignored when git is available, else a folder walk. */ +export function markdownFiles(root) { + try { + const out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", "*.md"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); + return out.split("\0").filter((f) => f && !f.split("/").some((p) => SKIP_DIRS.has(p)) && existsSync(join(root, f))).sort(); + } catch { + const found = []; + const walk = (dir) => { + for (const name of readdirSync(dir)) { + if (SKIP_DIRS.has(name)) continue; + const p = join(dir, name); + if (statSync(p).isDirectory()) walk(p); + else if (name.endsWith(".md")) found.push(relative(root, p).split(sep).join("/")); + } + }; + walk(root); + return found.sort(); + } +} + +/** Text with fenced code blocks and inline code blanked out, so line numbers stay the same. */ +function stripCode(text) { + const lines = text.split("\n"); + let fence = null; + return lines.map((line) => { + const m = /^\s*(`{3,}|~{3,})/.exec(line); + if (fence) { + if (m && m[1][0] === fence[0] && m[1].length >= fence.length) fence = null; + return ""; + } + if (m) { fence = m[1]; return ""; } + return line.replace(/(`+)[^`]*?\1/g, ""); + }).join("\n"); +} + +/** GitHub heading slug (github-slugger rules) for one heading's text. */ +export function slug(heading) { + const text = heading + .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1") + .replace(/<[^>]+>/g, "") + .replace(/[`*]/g, "") + .trim() + .toLowerCase(); + return text.replace(/[^\p{L}\p{N}\p{M}\p{Pc} -]/gu, "").replace(/ /g, "-"); +} + +/** Every anchor a Markdown file offers: heading slugs (with -1, -2 for repeats) and HTML id/name attributes. */ +export function anchors(text) { + const out = new Set(); + const seen = new Map(); + let fence = null; + for (const line of text.split("\n")) { + const f = /^\s*(`{3,}|~{3,})/.exec(line); + if (fence) { if (f && f[1][0] === fence[0] && f[1].length >= fence.length) fence = null; continue; } + if (f) { fence = f[1]; continue; } + const h = /^ {0,3}#{1,6}\s+(.*?)\s*#*\s*$/.exec(line); + if (h) { + const base = slug(h[1]); + const n = seen.get(base) ?? 0; + seen.set(base, n + 1); + out.add(n === 0 ? base : `${base}-${n}`); + } + for (const m of line.matchAll(/]*(?:id|name)="([^"]+)"/g)) out.add(m[1]); + } + return out; +} + +/** Relative link targets in one file, with line numbers. */ +export function links(text) { + const found = []; + stripCode(text).split("\n").forEach((line, i) => { + for (const m of line.matchAll(/!?\[[^\]]*\]\(\s*]+)>?(?:\s+"[^"]*")?\s*\)/g)) found.push({ target: m[1], line: i + 1 }); + for (const m of line.matchAll(/\b(?:href|src)="([^"]+)"/g)) found.push({ target: m[1], line: i + 1 }); + for (const m of line.matchAll(/^\s*\[[^\]]+\]:\s*(\S+)/g)) found.push({ target: m[1], line: i + 1 }); + }); + return found.filter((l) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(l.target)); +} + +/** Broken relative links under root. Each entry names the file, line, target and reason. */ +export function checkLinks(root) { + const broken = []; + const anchorCache = new Map(); + const files = markdownFiles(root); + let checked = 0; + for (const file of files) { + const text = readFileSync(join(root, file), "utf8"); + for (const { target, line } of links(text)) { + checked++; + const [rawPath, rawAnchor] = target.split("#", 2); + let path; + try { path = decodeURIComponent(rawPath); } catch { path = rawPath; } + const abs = path === "" ? join(root, file) : resolve(root, dirname(file), path); + if (!abs.startsWith(resolve(root))) { broken.push({ file, line, target, reason: "points outside the repo" }); continue; } + if (!existsSync(abs)) { broken.push({ file, line, target, reason: "file not found" }); continue; } + if (rawAnchor && abs.endsWith(".md") && statSync(abs).isFile()) { + if (!anchorCache.has(abs)) anchorCache.set(abs, anchors(readFileSync(abs, "utf8"))); + if (!anchorCache.get(abs).has(decodeURIComponent(rawAnchor).toLowerCase())) broken.push({ file, line, target, reason: "anchor not found" }); + } + } + } + return { files: files.length, links: checked, broken }; +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); + const result = checkLinks(root); + if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2)); + else { + for (const b of result.broken) console.log(`${b.file}:${b.line}: ${b.target} (${b.reason})`); + console.log(`${result.files} Markdown files, ${result.links} relative links, ${result.broken.length} broken`); + } + process.exitCode = result.broken.length === 0 ? 0 : 1; +} diff --git a/scripts/count-loc.mjs b/scripts/count-loc.mjs new file mode 100644 index 0000000..e2e80b2 --- /dev/null +++ b/scripts/count-loc.mjs @@ -0,0 +1,45 @@ +#!/usr/bin/env node +// Counts non-blank lines in packages/*/src, per package and in total. +// Run: node scripts/count-loc.mjs [--files] [--json]. Read only. +import { readdirSync, readFileSync, statSync } from "node:fs"; +import { join, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +const repo = fileURLToPath(new URL("../", import.meta.url)); +const SOURCE = /\.(ts|tsx|mts|js|mjs|css)$/; + +function walk(dir, out = []) { + for (const e of readdirSync(dir, { withFileTypes: true })) { + const p = join(dir, e.name); + if (e.isDirectory()) walk(p, out); + else if (SOURCE.test(e.name)) out.push(p); + } + return out; +} + +const nonBlank = (file) => readFileSync(file, "utf8").split("\n").filter((l) => l.trim() !== "").length; + +const packages = {}; +const files = {}; +let total = 0; +const pkgRoot = join(repo, "packages"); +for (const name of readdirSync(pkgRoot).sort()) { + const src = join(pkgRoot, name, "src"); + try { if (!statSync(src).isDirectory()) continue; } catch { continue; } + let sum = 0; + for (const f of walk(src).sort()) { + const n = nonBlank(f); + files[relative(repo, f)] = n; + sum += n; + } + packages[name] = sum; + total += sum; +} + +if (process.argv.includes("--json")) { + console.log(JSON.stringify({ total, packages, ...(process.argv.includes("--files") ? { files } : {}) }, null, 2)); +} else { + if (process.argv.includes("--files")) for (const [f, n] of Object.entries(files)) console.log(`${String(n).padStart(6)} ${f}`); + for (const [p, n] of Object.entries(packages)) console.log(`${String(n).padStart(6)} packages/${p}/src`); + console.log(`${String(total).padStart(6)} total non-blank lines`); +} diff --git a/scripts/demo.ts b/scripts/demo.ts deleted file mode 100644 index 659d934..0000000 --- a/scripts/demo.ts +++ /dev/null @@ -1,54 +0,0 @@ -// Demo for the launch GIF: two agents, two repos, one shared graph. Run: node scripts/demo.ts -import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { buildGraph, guardedWrite, readSnapshot, renderText, StaleWriteError, updateFile } from "../packages/core/src/index.ts"; - -const say = (s: string) => console.log(s); -const root = mkdtempSync(join(tmpdir(), "mozak-demo-")); - -function scope(rel: string, id: string, kind: "project" | "topic", links: string[]) { - const dir = join(root, rel); - mkdirSync(dir, { recursive: true }); - writeFileSync(join(dir, "README.md"), `# ${id}\n`); - writeFileSync(join(dir, "AGENTS.md"), `# ${id}\n`); - writeFileSync(join(dir, "mozak.md"), `---\nid: ${id}\nkind: ${kind}\nformat: 1\n---\n## Plan\n- [ ] start\n## Links\n${links.join("\n")}\n## Translations\n`); - return join(dir, "mozak.md"); -} - -const research = scope("vault/research", "research", "topic", []); -const api = scope("repos/api", "api", "project", ["- depends-on: [[research]]"]); -const cfg = { roots: [root] }; - -say("== graph before"); -say(renderText(buildGraph(cfg))); - -say("\n== agent A and agent B both read research/mozak.md"); -const a = readSnapshot(research); -const b = readSnapshot(research); -say(`A base ${a.hash.slice(0, 8)} B base ${b.hash.slice(0, 8)}`); - -say("\n== agent B writes first"); -guardedWrite(research, b.text.replace("- [ ] start", "- [ ] start\n- [ ] B: survey papers"), b.hash); -say("B: accepted"); - -say("\n== agent A writes from its stale base"); -try { - guardedWrite(research, a.text.replace("- [ ] start", "- [ ] start\n- [ ] A: collect datasets"), a.hash); -} catch (e) { - if (!(e instanceof StaleWriteError)) throw e; - say(`A: REFUSED ${e.message.split(": ")[1]}`); -} - -say("\n== agent A re-reads and retries"); -updateFile(research, (t) => t.replace("## Links", "- [ ] A: collect datasets\n## Links")); -say("A: accepted"); - -say("\n== agent on api adds an edge at the same time"); -updateFile(api, (t) => t.replace("## Translations", "- informs: [[research]]\n## Translations")); - -say("\n== research/mozak.md plan, both edits survived"); -say(readSnapshot(research).text.split("## Links")[0].split("## Plan")[1].trim()); - -say("\n== graph after"); -say(renderText(buildGraph(cfg))); diff --git a/scripts/readme-example.mjs b/scripts/readme-example.mjs new file mode 100644 index 0000000..52f889f --- /dev/null +++ b/scripts/readme-example.mjs @@ -0,0 +1,64 @@ +#!/usr/bin/env node +// Reproduces the short example in README.md on a throwaway scope in a temp folder. +// Run after `npm run build`: node scripts/readme-example.mjs +// It never touches a real inventory. Synthetic data only. The temp folder is removed at the end. +import { spawnSync } from "node:child_process"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const cli = fileURLToPath(new URL("../packages/cli/dist/index.js", import.meta.url)); +const root = mkdtempSync(join(tmpdir(), "mozak-readme-example-")); +const at = new Date(Date.now() - 60_000).toISOString(); +let seq = 0; + +function mozak(args, { json = false } = {}) { + const p = spawnSync(process.execPath, [cli, ...args, "--config", join(root, "mozak-inventory.json"), ...(json ? ["--json"] : [])], { encoding: "utf8", timeout: 30_000 }); + // stdout only: write routes print a "not committed to git" note on stderr, which is not part of the answer. + return { code: p.status, out: p.stdout ?? "" }; +} +function request(body) { + const path = join(root, `request-${seq++}.json`); + writeFileSync(path, JSON.stringify(body)); + return path; +} +function show(label, args, r) { + console.log(`$ mozak ${args.join(" ")} # ${label}`); + let text = r.out.trimEnd(); + try { + // Write routes answer in JSON. Keep only the lines a reader needs. + const j = JSON.parse(text); + text = [`status: ${j.status}`, `committed: ${j.committed}`, ...(j.issues ?? []).map((i) => `${i.code}: ${i.message}`)].join("\n"); + } catch { /* human-readable output, print as is */ } + console.log(text); + console.log(`(exit ${r.code})\n`); +} + +try { + const app = join(root, "my-app"); + mkdirSync(app); + writeFileSync(join(app, "README.md"), "# my-app\n"); + writeFileSync(join(app, "AGENTS.md"), "# Agents\n"); + writeFileSync(join(root, "mozak-inventory.json"), JSON.stringify({ format: "mozak.local/v3", scopes: [{ id: "my-app", root: "./my-app" }] })); + + const init = mozak(["scope", "init", "--scope", "my-app", "--request", request({ operationId: "init-my-app", scopeId: "my-app", kind: "project", title: "my-app", expectedAbsent: { graph: true, bridge: true }, ownerRef: "synthetic-owner:readme-example", ownerMessageAt: at })], { json: true }); + if (init.code !== 0) throw new Error(`scope init failed: ${init.out}`); + + const ctx = mozak(["context", "--scope", "my-app"], { json: true }); + const expected = JSON.parse(ctx.out).snapshot; + const content = (title, statement) => ({ + title, purpose: "Example plan for the README", rationale: "Synthetic example", + outcomes: [{ id: "works", statement, acceptance: "objective", criterion: "A test passes" }], + constraints: [], nonGoals: [], questions: [], + sources: [{ id: "example", locator: "synthetic:readme-example", anchor: null, observedAt: at, version: null, limitations: ["Synthetic example"] }], + }); + // Two agents read the same snapshot, then both propose. + const a = request({ operationId: `op-a-${Date.now()}`, scopeId: "my-app", expected, action: "propose", payload: { planId: "dark-mode", content: content("Add dark mode", "The app has a dark theme") } }); + const b = request({ operationId: `op-b-${Date.now()}`, scopeId: "my-app", expected, action: "propose", payload: { planId: "csv-export", content: content("Export to CSV", "Users can export a table as CSV") } }); + show("agent A proposes", ["plan", "propose", "--scope", "my-app", "--request", "a.json"], mozak(["plan", "propose", "--scope", "my-app", "--request", a])); + show("agent B proposes from the same, now old, snapshot", ["plan", "propose", "--scope", "my-app", "--request", "b.json"], mozak(["plan", "propose", "--scope", "my-app", "--request", b])); + show("what is in the plan now", ["plans", "--scope", "my-app"], mozak(["plans", "--scope", "my-app"])); +} finally { + rmSync(root, { recursive: true, force: true }); +} diff --git a/scripts/render_gif.py b/scripts/render_gif.py deleted file mode 100644 index 1cd542c..0000000 --- a/scripts/render_gif.py +++ /dev/null @@ -1,74 +0,0 @@ -"""Render a terminal-style GIF from the captured output of scripts/demo.ts. -The text is the real program output, only the typing/pacing is simulated. -Usage: python3 scripts/render_gif.py scratch/gif/demo.txt docs/demo.gif -""" -import subprocess, sys, shutil, os, re -from PIL import Image, ImageDraw, ImageFont - -src, out = sys.argv[1], sys.argv[2] -lines = open(src).read().rstrip("\n").split("\n") - -FONT = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", 18) -W, H, PAD, LH = 980, 0, 24, 26 -BG, FG, DIM = (22, 22, 30), (205, 214, 244), (127, 132, 156) -GREEN, RED, BLUE, YELLOW = (166, 227, 161), (243, 139, 168), (137, 180, 250), (249, 226, 175) - -def color(line): - if line.startswith("=="): return BLUE - if "REFUSED" in line: return RED - if line.endswith("accepted"): return GREEN - if "both edits survived" in line: return GREEN - if line.startswith("A base"): return YELLOW - return FG - -# Group lines into steps so each section appears together, with a pause after each. -steps, cur = [], [] -for l in lines: - if l.startswith("==") and cur: - steps.append(cur); cur = [] - cur.append(l) -if cur: steps.append(cur) - -visible_rows = 30 -H = PAD * 2 + LH * (visible_rows + 1) -os.makedirs("scratch/gif/frames", exist_ok=True) -for f in os.listdir("scratch/gif/frames"): - os.remove(os.path.join("scratch/gif/frames", f)) - -shown, frames = [("$ node scripts/demo.ts", FG), ("", FG)], [] -def frame(extra=None, hold=1): - img = Image.new("RGB", (W, H), BG) - d = ImageDraw.Draw(img) - d.rectangle((0, 0, W, 34), fill=(30, 30, 46)) - for i, c in enumerate([(243, 139, 168), (249, 226, 175), (166, 227, 161)]): - d.ellipse((14 + i * 22, 11, 26 + i * 22, 23), fill=c) - d.text((W // 2 - 90, 8), "mozak: two agents, one graph", font=FONT, fill=DIM) - rows = shown + ([extra] if extra else []) - rows = rows[-visible_rows:] - y = 34 + PAD - for text, col in rows: - d.text((PAD, y), text, font=FONT, fill=col) - y += LH - frames.append((img, hold)) - -frame(hold=8) -for step in steps: - for l in step: - if l.strip() == "": - shown.append(("", FG)); continue - # type the heading line fast, reveal others whole - shown.append((l, color(l))) - frame(hold=3 if l.startswith("==") else 2) - hold = 14 if any("REFUSED" in l for l in step) else 8 - frames[-1] = (frames[-1][0], hold) -frame(hold=30) - -# write frames at 10 fps, repeating by hold count -n = 0 -for img, hold in frames: - for _ in range(hold): - img.save(f"scratch/gif/frames/f{n:04d}.png"); n += 1 -os.makedirs(os.path.dirname(out), exist_ok=True) -subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-framerate", "10", "-i", "scratch/gif/frames/f%04d.png", - "-vf", "split[a][b];[a]palettegen=max_colors=64[p];[b][p]paletteuse", out], check=True) -print(f"{n} frames, {n/10:.1f}s, {os.path.getsize(out)/1024:.0f} KB -> {out}") diff --git a/scripts/verify-dup.ts b/scripts/verify-dup.ts new file mode 100644 index 0000000..fdc6a96 --- /dev/null +++ b/scripts/verify-dup.ts @@ -0,0 +1,49 @@ +// V-dup verifier (D3 goal 1). Exits non-zero when a gate fails. +// +// node scripts/verify-dup.ts synthetic public mirror: all gates, prints metrics as JSON +// node scripts/verify-dup.ts --config FILE [--details] [--max-pairs 4] +// a real inventory, read only: pooled pair count against the +// budget, the raw lexical count for comparison, labels. +// --details adds scope/plan ids per pair (never plan text). +// The real run never writes: the usage log is turned off and scopes are read without git or network. +import { buildMirror, verifyMirror } from "../packages/core/test/vdup-fixture.ts"; +import { loadInventory, rawPooledPairs, readScopeQuiet, similarReport, type ScopeState } from "../packages/core/src/index.ts"; + +const args = process.argv.slice(2); +const flag = (name: string) => args.includes(`--${name}`); +const value = (name: string) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; }; + +if (value("config")) { + process.env.MOZAK_USAGE_LOG = "0"; + const maxPairs = Number(value("max-pairs") ?? 4); + const inv = loadInventory(value("config")!); + const started = performance.now(); + const scopes: { id: string; state: ScopeState }[] = []; + const failed: string[] = []; + for (const e of inv.scopes) { + try { scopes.push({ id: e.id, state: readScopeQuiet(e).state }); } catch { failed.push(e.id); } + } + const report = similarReport(scopes); + const ms = Math.round(performance.now() - started); + const byLabel: Record = {}; + for (const p of report.pairs) byLabel[p.label] = (byLabel[p.label] ?? 0) + 1; + const out = { + scopes: scopes.length, failedScopes: failed, plans: report.plans, rawLexicalPairs: rawPooledPairs(scopes), + pooledPairs: report.pairs.length, maxPairs, byLabel, templateFiltered: report.templateFiltered, moved: report.moved.length, ms, + ...(flag("details") ? { pairs: report.pairs.map((p) => ({ label: p.label, rule: p.rule, a: `${p.a.scope}/${p.a.planId}`, b: `${p.b.scope}/${p.b.planId}`, why: p.why })), movedPlans: report.moved.map((x) => `${x.scope}/${x.planId}`) } : {}), + }; + console.log(JSON.stringify(out, null, 2)); + const ok = report.pairs.length <= maxPairs && failed.length === 0; + if (!ok) console.error(`V-dup real run FAILED: ${report.pairs.length} pooled pairs (budget ${maxPairs}), ${failed.length} unreadable scopes`); + process.exit(ok ? 0 : 1); +} + +const m = buildMirror(); +try { + const r = verifyMirror(m); + console.log(JSON.stringify(r, null, 2)); + if (!r.ok) console.error(`V-dup mirror FAILED: ${r.failures.join("; ")}`); + process.exitCode = r.ok ? 0 : 1; +} finally { + m.cleanup(); +} diff --git a/scripts/verify-latency.ts b/scripts/verify-latency.ts new file mode 100644 index 0000000..45cb1f9 --- /dev/null +++ b/scripts/verify-latency.ts @@ -0,0 +1,88 @@ +// V-latency verifier for S6 (D3 goal 3). Exits non-zero when a budget is exceeded. +// +// node scripts/verify-latency.ts synthetic: 23 scopes in one vault repo, 10 plans each +// node scripts/verify-latency.ts --config FILE a real inventory, read only (plans.md is printed, never written) +// options: --runs N (default 5), --plans-md-ms 1000, --locators-ms 300 +// +// Budgets (D3): plans.md under 1 s for the inventory's scopes, locator resolution under 300 ms. Each budget is checked +// on the slowest of N in-process runs. The CLI run of `plans-md --print` (process start included) is checked too. +// The usage log is off, so nothing is written next to the inventory. +import { spawnSync } from "node:child_process"; +import { existsSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { LocatorResolver, loadInventory, planCitations, plansIndex, readScopeQuiet } from "../packages/core/src/index.ts"; +import { cleanupS6, s6world } from "../packages/core/test/s6-fixture.ts"; + +process.env.MOZAK_USAGE_LOG = "0"; +const args = process.argv.slice(2); +const value = (name: string) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; }; +const runs = Number(value("runs") ?? 5); +const budget = { plansMd: Number(value("plans-md-ms") ?? 1000), locators: Number(value("locators-ms") ?? 300) }; + +let config = value("config"); +let synthetic = false; +if (!config) { + synthetic = true; + const scopes: Record = {}; + for (let i = 1; i <= 23; i++) scopes[`s${i}`] = `vault/${i % 2 ? "research" : "personal"}/s${i}`; + const w = s6world(scopes, { repos: ["vault"] }); + for (let i = 1; i <= 23; i++) for (let k = 1; k <= 10; k++) { + w.propose(`s${i}`, `plan-${k}`, { title: `Synthetic topic ${i} item ${k}`, sources: [{ locator: "README.md" }, { locator: `[[note-${k}]]` }] }, k % 3 ? "approve" : "await"); + } + config = w.config; +} + +const inv = loadInventory(config); +const ms = (f: () => void) => { const t = performance.now(); f(); return performance.now() - t; }; + +let files = 0, plans = 0; +const plansMdRuns = Array.from({ length: runs }, () => ms(() => { + const r = plansIndex(inv, { write: false }); + files = r.files.length; + plans = r.files.reduce((n, f) => n + f.plans, 0); +})); + +let locators = 0; +const statusCounts: Record = {}; +const locatorRuns = Array.from({ length: runs }, () => ms(() => { + const resolver = new LocatorResolver(inv); + locators = 0; + for (const k of Object.keys(statusCounts)) delete statusCounts[k]; + for (const entry of inv.scopes) { + let state; + try { state = readScopeQuiet(entry).state; } catch { continue; } + for (const p of state.plans) for (const c of planCitations(p)) { + const r = resolver.resolve(entry, c.locator, c.anchor); + locators++; + statusCounts[r.status] = (statusCounts[r.status] ?? 0) + 1; + } + } +})); + +const cli = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "packages", "cli", "dist", "index.js"); +let cliMs: number | null = null; +if (existsSync(cli)) { + const t = performance.now(); + const r = spawnSync(process.execPath, ["--no-warnings", cli, "plans-md", "--config", config, "--print", "--json"], { encoding: "utf8", env: { ...process.env, MOZAK_USAGE_LOG: "0" } }); + cliMs = performance.now() - t; + if (r.status !== 0 && r.status !== 6) { console.error(`plans-md CLI exited ${r.status}: ${r.stderr}`); cliMs = Infinity; } +} + +const round = (x: number) => Math.round(x * 10) / 10; +const max = (xs: number[]) => Math.max(...xs); +const median = (xs: number[]) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)]; +const result = { + synthetic, scopes: inv.scopes.length, runs, + plansMd: { files, plans, maxMs: round(max(plansMdRuns)), medianMs: round(median(plansMdRuns)), budgetMs: budget.plansMd, cliMs: cliMs === null ? null : round(cliMs) }, + locators: { count: locators, statuses: statusCounts, maxMs: round(max(locatorRuns)), medianMs: round(median(locatorRuns)), budgetMs: budget.locators }, +}; +console.log(JSON.stringify(result, null, 2)); +const failures = [ + ...(max(plansMdRuns) > budget.plansMd ? [`plans.md took ${round(max(plansMdRuns))} ms (budget ${budget.plansMd})`] : []), + ...(cliMs !== null && cliMs > budget.plansMd ? [`plans-md CLI took ${round(cliMs)} ms (budget ${budget.plansMd})`] : []), + ...(max(locatorRuns) > budget.locators ? [`locator resolution took ${round(max(locatorRuns))} ms (budget ${budget.locators})`] : []), +]; +if (synthetic) cleanupS6(); +if (failures.length) console.error(`V-latency FAILED: ${failures.join("; ")}`); +process.exitCode = failures.length ? 1 : 0; diff --git a/scripts/verify-old-client-sidecar.sh b/scripts/verify-old-client-sidecar.sh new file mode 100755 index 0000000..dfbbe37 --- /dev/null +++ b/scripts/verify-old-client-sidecar.sh @@ -0,0 +1,37 @@ +#!/bin/sh +# Old-client check on a synthetic temp scope: the installed mozak CLI (released code, no annotations support) +# reads and writes a scope that has a mozak.annotations.json made by this branch. Never touches a real inventory. +set -eu +NEW="$(cd "$(dirname "$0")/.." && pwd)/packages/cli/dist/index.js" +OLD="${OLD_CLI:-$HOME/.local/share/mozak-next/node_modules/@mozak/cli/dist/index.js}" +BASE="$(mktemp -d "${TMPDIR:-/tmp}/mozak-s4-old-client.XXXXXX")" +trap 'rm -rf "$BASE"' EXIT +mkdir -p "$BASE/alpha"; printf 'Synthetic\n' > "$BASE/alpha/README.md"; printf 'Synthetic\n' > "$BASE/alpha/AGENTS.md" +printf '{"format":"mozak.local/v3","scopes":[{"id":"alpha","root":"./alpha"}]}' > "$BASE/inv.json" +# Annotations are off unless the settings file next to the inventory turns them on for the scope. +printf '{"format":"mozak.settings/v1","scopes":{"alpha":{"annotations":true}}}' > "$BASE/mozak-settings.json" +NOW=2026-10-21T08:00:00.000Z +printf '{"operationId":"init","scopeId":"alpha","kind":"project","title":"Synthetic","expectedAbsent":{"graph":true,"bridge":true},"ownerRef":"synthetic","ownerMessageAt":"%s"}' "$NOW" > "$BASE/init.json" +node "$NEW" scope init --config "$BASE/inv.json" --scope alpha --request "$BASE/init.json" > /dev/null +snap() { node "$1" context --config "$BASE/inv.json" --scope alpha --json | jq -c .snapshot; } +propose() { # $1 cli, $2 plan id + printf '{"operationId":"p-%s","scopeId":"alpha","expected":%s,"action":"propose","payload":{"planId":"%s","content":{"constraints":[],"nonGoals":[],"outcomes":[{"acceptance":"objective","criterion":"c","id":"o","statement":"s"}],"purpose":"p","questions":[],"rationale":"r","sources":[],"title":"Synthetic %s"}}}' "$2" "$(snap "$1")" "$2" "$2" > "$BASE/p.json" + node "$1" plan propose --config "$BASE/inv.json" --scope alpha --request "$BASE/p.json" > "$BASE/p.out"; echo "propose $2 via $3: exit 0" +} +propose "$NEW" a branch; propose "$NEW" b branch +printf '{"operationId":"annot-1","scopeId":"alpha","expectedAnnotations":{"exists":false,"sha256":null},"ownerRef":"synthetic","ownerMessageAt":"%s","items":[{"kind":"ref","planId":"b","target":"alpha/a","relation":"needs","evidence":"b needs a"}]}' "$NOW" > "$BASE/a.json" +node "$NEW" annotate --config "$BASE/inv.json" --scope alpha --request "$BASE/a.json" > /dev/null +echo "annotate via branch: exit 0" +[ -f "$BASE/alpha/mozak.annotations.json" ] || { echo "no sidecar written" >&2; exit 1; } +SIDE="$(shasum -a 256 "$BASE/alpha/mozak.annotations.json" | cut -d' ' -f1)" +echo "old cli version: $(node "$OLD" --version)" +for r in "context --scope alpha --json" "plans --scope alpha --json" "check --scope alpha --json"; do + set +e; node "$OLD" $r --config "$BASE/inv.json" > /dev/null; code=$?; set -e + echo "old $r: exit $code" +done +propose "$OLD" c old-cli +set +e; node "$OLD" check --config "$BASE/inv.json" --scope alpha --json > /dev/null; echo "old check after old write: exit $?"; set -e +[ "$SIDE" = "$(shasum -a 256 "$BASE/alpha/mozak.annotations.json" | cut -d' ' -f1)" ] || { echo "sidecar changed by old client" >&2; exit 1; } +echo "sidecar unchanged by old client" +set +e; node "$NEW" check --config "$BASE/inv.json" --scope alpha --json > /dev/null; echo "branch check after old write: exit $?"; set -e +node "$NEW" graph --config "$BASE/inv.json" --scope alpha --json | jq -c "{edges: .graph.counts.edges, dangling: .graph.counts.dangling, nodes: .graph.counts.nodes}" diff --git a/skills/mozak/SKILL.md b/skills/mozak/SKILL.md index de7d774..ec911d9 100644 --- a/skills/mozak/SKILL.md +++ b/skills/mozak/SKILL.md @@ -43,6 +43,7 @@ Offer "show plans" for the full list. That request reads plans again and follows - **Before calling `propose`:** Always inspect existing non-completed plans (`unaccepted`, `open`, `paused`) in `context` / `plans` for the scope. If a plan covering the same topic, workflow, or outcome already exists, **revise that existing plan (`revise`)** instead of creating a second plan. - **Core duplicate guard (`duplicate-plan-candidate`, exit 3):** `propose` refuses when a non-completed plan in the same scope has overlapping title, ID, or outcomes. If that happens, show the matching plan(s) to the owner and ask whether to revise/merge into the existing plan or create a separate plan. Only pass `"distinctFromPlanIds": ["existing-plan-id"]` in the `propose` payload after the owner explicitly asks for a separate plan. +- **Similar plans in other scopes:** `node {{MOZAK_CLI}} similar --config INVENTORY --all` (MCP `mozak_similar`) lists duplicate, overlapping and superseding plans across scopes. It only suggests. A cross-scope duplicate is a move: ask the owner, never merge across scopes. - **Merging two existing non-completed plans (`mergeFromPlanId`):** When two non-completed plans in a scope overlap, propose a unified revision on the target plan (`plan revise` / `mozak_revise`) with `"mergeFromPlanId": "source-plan-id"` in the payload, combining their outcomes, constraints, non-goals, questions, and sources. Then show the direction review (`review show --purpose approve-direction`) and ask the owner to approve. On `approve-direction`, Core atomically folds the source plan's observations, reasoning links, and discussion questions into the target plan and removes the duplicate source plan so only one clean plan remains. - **Completed plans stay immutable:** Never merge a `completed` plan. For follow-up work after a completed plan, propose a new plan and cite the completed work in `content.sources`. - **Deleting a plan (`plan delete`, owner only):** When the owner asks to delete plans, or a plan is superseded by one in another scope, show the plan ids and ask once. On a yes, run `plan delete --plans A,B` with the owner flags (see `references/routes.md`). The plans then no longer exist. Rejecting or pausing is not deleting. After deleting, list the scheduled jobs in the agent host that name the plan (for example jcode `ScheduleWakeup` list) and offer to cancel them. Never edit a scope's mozak.json or mozak.md by hand to delete or change a plan: if a route is missing, say so and stop. diff --git a/skills/mozak/references/routes.md b/skills/mozak/references/routes.md index 2f9b1ea..740fe62 100644 --- a/skills/mozak/references/routes.md +++ b/skills/mozak/references/routes.md @@ -19,6 +19,10 @@ Run `node {{MOZAK_CLI}} --help` at session start. If a route is missing, stop. | `node {{MOZAK_CLI}} plans --config INVENTORY --scope ID --json` | Plan list | | `node {{MOZAK_CLI}} review show --config INVENTORY --scope ID --plan PLAN [--purpose P] [--outcome ID] --json` | Review subject for one decision | | `node {{MOZAK_CLI}} check --config INVENTORY --scope ID --json` | Findings. Never repairs. | +| `node {{MOZAK_CLI}} graph --config INVENTORY (--scope ID \| --all) --json` | Cross-plan refs from owner annotations and how each target resolves | +| `node {{MOZAK_CLI}} ready --config INVENTORY (--scope ID \| --all) --json` | Open plans whose `needs` are met, by deadline. Blocked and superseded plans listed apart. Advisory only | +| `node {{MOZAK_CLI}} plans --config INVENTORY --scope ID --sort deadline --json` | Plan list ordered by owner or inferred deadline | +| `node {{MOZAK_CLI}} focus list --config INVENTORY [--scope ID] --json` | The owner's starred plans per scope (MCP `mozak_focus`). A sidebar marker for the owner: read it, never write it, and it grants nothing | Purposes (`review show`, `review decide`): `approve-direction` (default for a pending direction), `reject-pending`, `reconsider`, `pause`, `resume`, `approve-implementation`, `revoke-implementation`, `accept-outcome` (needs `--outcome`). @@ -88,6 +92,17 @@ Removes plans so they no longer exist in `mozak.json` or `mozak.md`. Use it only An unambiguous pause instruction stops host work first. The host may then persist it using the current pause subject, with the real provenance. The provenance record states that the instruction preceded this generated review. This covers stopping only. It never covers approval, resume, or broadening. +### Owner annotations (`annotate`) + +`node {{MOZAK_CLI}} annotate --config INVENTORY --scope ID --request FILE` writes only `mozak.annotations.json`. It never changes `mozak.json`, `mozak.md`, approvals or grants, and agent snapshots stay valid. + +- Items: `{ "kind": "ref", "planId", "target": "scope/plan[#outcome]", "relation": "needs" | "informs" | "supersedes", "fromOutcome"?, "evidence" }`, `{ "kind": "deadline", "planId", "date": "YYYY-MM-DD", "evidence" }`, `{ "kind": "remove-ref", "planId", "refId" }`, `{ "kind": "clear-deadline", "planId" }`. +- The agent proposes at most 7 items at a time. Show each item with its evidence sentence and its `itemDigest` (sha256 of the canonical item). The owner may approve all, some or none. Send only the approved items, each with its `itemDigest`. +- Request: `{ "operationId", "scopeId", "expectedAnnotations": { "exists", "sha256" }, "ownerRef", "ownerMessageAt", "items": [...] }`. `expectedAnnotations` is the sidecar token the owner saw (`{ "exists": false, "sha256": null }` when there is no file). It is the only CAS input. Read it from `graph --scope ID --json` as `annotations.ID`. +- `needs` is advisory. It orders `ready` and shows in the plugin. Nothing refuses a write because of it. +- Several dates in plan prose are candidates. Propose one `deadline` item and let the owner pick. +- Annotations are off by default. The owner turns them on per scope with `scopes..annotations: true` in the `mozak-settings.json` next to the inventory. Otherwise `annotate` is refused (`annotations-disabled`), and on repo-mode remote scopes always (`annotations-refused-remote`). + ## Review digest and CAS The flag forms apply these rules. An identical retry replays its receipt. A reused `operationId` with different input is `operation-conflict` (exit 3). After `stale-input`, an unchanged subject (scope, plan, purpose, revision and content digest, spec and bounds digest, authorization, `reviewDigest`) may reuse the unconsumed owner confirmation with a fresh `expected` and new `operationId`. A changed subject needs redisplay and a fresh "yes". diff --git a/tsconfig.base.json b/tsconfig.base.json index 37346ec..d6364e2 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -4,6 +4,11 @@ "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noImplicitOverride": true, "declaration": true, "composite": true, "skipLibCheck": true, diff --git a/versions.json b/versions.json index 13ce599..2aa67b3 100644 --- a/versions.json +++ b/versions.json @@ -7,5 +7,6 @@ "0.4.5": "1.14.4", "0.4.6": "1.14.4", "0.4.7": "1.14.4", - "0.4.8": "1.14.4" + "0.4.8": "1.14.4", + "0.5.0": "1.14.4" }