Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions apps/cli/src/bin.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#!/usr/bin/env node
import { readFileSync } from 'node:fs';
import { realpath } from 'node:fs/promises';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { basename, resolve } from 'node:path';
Expand Down Expand Up @@ -51,7 +52,9 @@ if (command.kind === 'output') {
} else {
const dataDir = resolveDataDir(process.env, process.platform, homedir());
try {
const result = await inspectWorkspace(command.path);
const home = homedir();
const knownHomes = [home, await realpath(home).catch(() => home)];
const result = await inspectWorkspace(command.path, { knownHomes });
const graph = buildArchitectureGraph(result);
const prepareRuntime = async (enabled: boolean) => {
const runtime = await prepareStore({
Expand Down Expand Up @@ -106,7 +109,14 @@ if (command.kind === 'output') {
} else if (command.graph) {
process.stdout.write(`${JSON.stringify(graph, null, 2)}\n`);
} else if (command.json) {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
// Allowlist: the absolute root identifies the user and machine, so it is never printed.
const portable = {
version: result.version,
manifests: result.manifests,
diagnostics: result.diagnostics,
inspectedEntries: result.inspectedEntries,
};
process.stdout.write(`${JSON.stringify(portable, null, 2)}\n`);
} else {
process.stdout.write(`Archwise — local inventory (${result.manifests.length} manifests)\n`);
for (const item of result.manifests) {
Expand Down
20 changes: 16 additions & 4 deletions apps/cli/src/inventory.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
import { resolve, relative, join, sep } from 'node:path';
import { redactSensitiveText } from '@archwise/domain';

const IGNORED = new Set([
'.git',
Expand Down Expand Up @@ -31,8 +32,17 @@ export interface InventoryResult {
readonly inspectedEntries: number;
}

export interface InventoryOptions {
/** The running user's home directories (as given and resolved), redacted from manifest text. */
readonly knownHomes?: readonly string[];
}

/** Inspect manifests as data. Do not execute/import any code in the target workspace. */
export async function inspectWorkspace(rootInput: string): Promise<InventoryResult> {
export async function inspectWorkspace(
rootInput: string,
options: InventoryOptions = {},
): Promise<InventoryResult> {
const redact = (text: string): string => redactSensitiveText(text, options.knownHomes ?? []);
const root = await realpath(resolve(rootInput));
if (!(await lstat(root)).isDirectory()) throw new Error('Workspace root must be a directory');
const manifests: ManifestEvidence[] = [];
Expand Down Expand Up @@ -82,6 +92,8 @@ export async function inspectWorkspace(rootInput: string): Promise<InventoryResu
const deps = [data.dependencies, data.devDependencies].flatMap((value) =>
value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value) : [],
);
// Manifest text is untrusted: home directories and secret shapes never leave this boundary.
const dependencyNames = deps.map(redact);
const frameworks = [
'next',
'expo',
Expand All @@ -91,12 +103,12 @@ export async function inspectWorkspace(rootInput: string): Promise<InventoryResu
'express',
'@nestjs/core',
];
const framework = frameworks.find((item) => deps.includes(item)) ?? null;
const framework = frameworks.find((item) => dependencyNames.includes(item)) ?? null;
manifests.push({
path: relativePath,
name: typeof data.name === 'string' ? data.name : relativePath,
name: typeof data.name === 'string' ? redact(data.name) : relativePath,
framework,
dependencies: [...new Set(deps)].sort(),
dependencies: [...new Set(dependencyNames)].sort(),
});
} catch {
diagnostics.push(`Invalid or unreadable manifest: ${relativePath}`);
Expand Down
37 changes: 37 additions & 0 deletions apps/cli/tests/inventory.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,40 @@ test('reports malformed manifests without failing the entire scan', async () =>
await rm(root, { recursive: true, force: true });
}
});

test('redacts home directories and secret shapes in names read from manifests', async () => {
const root = await mkdtemp(join(tmpdir(), 'archwise-redact-'));
const token = 'AKIA' + 'ABCDEFGHIJKLMNOP';
try {
await mkdir(join(root, 'a'), { recursive: true });
await mkdir(join(root, 'b'), { recursive: true });
await writeFile(
join(root, 'a', 'package.json'),
JSON.stringify({ name: '/Users/alex/app', dependencies: { [`dep-${token}`]: '1' } }),
);
await writeFile(join(root, 'b', 'package.json'), JSON.stringify({ name: `dep-${token}` }));
const result = await inspectWorkspace(root);
expect(result.manifests.map((item) => item.name)).toEqual(['~/app', 'dep-[redacted]']);
expect(result.manifests[0]?.dependencies).toEqual(['dep-[redacted]']);
const text = JSON.stringify(result.manifests);
expect(text).not.toContain('/Users/alex');
expect(text).not.toContain(token);
} finally {
await rm(root, { recursive: true, force: true });
}
});

test('redacts the running user home directory supplied by the caller', async () => {
const root = await mkdtemp(join(tmpdir(), 'archwise-home-'));
try {
await writeFile(
join(root, 'package.json'),
JSON.stringify({ name: '/home/alex/app', dependencies: { '/home/feed': '1' } }),
);
const result = await inspectWorkspace(root, { knownHomes: ['/home/alex'] });
expect(result.manifests[0]?.name).toBe('~/app');
expect(result.manifests[0]?.dependencies).toEqual(['/home/feed']);
} finally {
await rm(root, { recursive: true, force: true });
}
});
6 changes: 5 additions & 1 deletion docs/alpha-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The CLI starts a server bound to `127.0.0.1` on an available port. If the browse
node apps/cli/dist/bin.js --path /absolute/path/to/your/project --graph
```

Use `--json` for the inventory instead of the graph, or `--serve --no-open` to avoid automatic browser launch.
Use `--json` for the inventory instead of the graph, or `--serve --no-open` to avoid automatic browser launch. Both JSON outputs use repository-relative paths and omit the absolute project root. They still contain your package names, so review them before sharing.

## What to verify

Expand Down Expand Up @@ -58,6 +58,10 @@ Use `--json` for the inventory instead of the graph, or `--serve --no-open` to a
- Default analysis reads project files; it never executes scripts from the inspected repository. No cloud account or remote AI is required.
- Browser access requires a one-time local session URL; do not share the URL or browser session cookie.

## If the local store fails

Archwise never deletes your sessions to recover. When the store is corrupt it moves the file aside, starts a fresh store and prints where the old file is. When the store was written by a newer Archwise, or an upgrade fails, it exits with code 2 and leaves the file untouched. It also exits with code 2 when the data directory is not writable. Run with `--no-store` to keep inspecting without sessions, or set `ARCHWISE_DATA_DIR` to use another directory. The full table is in [Sessions: recovery and failures](sessions.md#recovery-and-failures).

## Verified automated checks

The `main` branch passes the full `pnpm check` matrix on Linux, macOS and Windows using Node 24 and Node 26, including an authenticated HTTP smoke test of discovery → graph → server → compiled Studio assets. The `Browser Studio Smoke` workflow also exercises the Studio in headless Chromium on Ubuntu (see [Browser QA](browser-qa.md)). **Visual review, touch input, Safari/Firefox and OS-specific browser launch are still verified manually.**
Expand Down
20 changes: 16 additions & 4 deletions docs/implementation-roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@ Finalization does not mean development stops. It establishes a reliable open-sou

## Current state

Snapshot as of 2026-11-15, after PRs #5, #6 and #7 merged into `main`. Issues and milestones remain the live tracker.
Snapshot as of 2026-11-16, after PRs #5 to #12 and the Phase 2 redaction change. Issues and milestones remain the live tracker.

| Phase | State on `main` | What is missing for the exit gate |
|---|---|---|
| 0 | Complete (2026-11-15) | — |
| 1 | Complete (2026-11-15) | — |
| 2 | Partial: graph contracts; SQLite store with ports, migrations, backup and recovery; sessions with Studio autosave and resume | Export redaction of home paths; storage recovery in an end-user release guide |
| 2 | Complete (2026-11-16) | — |
| 3 | Alpha only: manifest-only inventory in `apps/cli` | Budgets, ignore rules, symlink and nested-repository handling, `--repo` / `--workspace`, persisted scan metadata |
| 4 | Alpha only: Node package manifests | Analyzer SDK, TS imports, HTTP/DB/queue detectors, Compose, golden graphs |
| 5 | Alpha only: protected loopback server and Svelte Flow Studio | SSE progress, evidence navigation from domain revisions, accessibility, large-graph strategy |
Expand Down Expand Up @@ -139,13 +139,25 @@ Detailed execution plan: [`superpowers/plans/2026-11-08-archwise-foundation.md`]

## Phase 2 — Domain contracts and local persistence

Status: in progress. The graph-contracts slice is implemented in `@archwise/domain` and `@archwise/schemas`. It covers the validated, immutable and canonically serialized `archwise.graph` v1 revision, strict import, and sandbox base references; see the [spec](superpowers/specs/2026-11-11-graph-contracts-design.md). The sessions slice adds the following (see [Sessions](sessions.md) and [ADR 0006](decisions/0006-local-store-node-sqlite.md)):
Status: complete (2026-11-16). The graph-contracts slice is implemented in `@archwise/domain` and `@archwise/schemas`. It covers the validated, immutable and canonically serialized `archwise.graph` v1 revision, strict import, and sandbox base references; see the [spec](superpowers/specs/2026-11-11-graph-contracts-design.md). The sessions slice adds the following (see [Sessions](sessions.md) and [ADR 0006](decisions/0006-local-store-node-sqlite.md)):
- application store ports and a `SessionService`;
- the `@archwise/storage` SQLite adapter, with transactional migrations, pre-migration backup, corruption quarantine and refusal of newer schemas;
- revision recording from discovery;
- the protected session API and `--sessions` / `--no-store`.

The Studio uses the store: autosave, a session list, resume, a changed-architecture notice and `--resume`. Still open: redaction of absolute home paths in exports. The phase exit gate is not yet satisfied.
The Studio uses the store: autosave, a session list, resume, a changed-architecture notice and `--resume`. Manifest text is redacted at the discovery boundary, and the graph validator rejects labels with home directories or secret shapes ([Security](security.md#redaction-at-the-discovery-boundary)).

Exit-gate evidence:

| Exit criterion | Evidence |
|---|---|
| Domain and schemas stay independent of Node APIs and frameworks | `scripts/check-boundaries.mjs` rules with regression tests in `scripts/tests/boundaries.test.mjs`, run by `pnpm check` |
| The same fixture serializes identically across platforms | The golden canonical-bytes test in `packages/schemas/tests/graph-json.test.ts` passes on the CI matrix (Linux, macOS, Windows × Node 24, 26) |
| Corrupt or future-version data fails safely with actionable diagnostics | Graph import rejects future versions (`unsupported-future-version`); the store quarantines corrupt files and refuses newer schemas untouched (`packages/storage/tests/lifecycle.test.ts`) |
| Storage recovery is documented and tested | [Sessions: recovery and failures](sessions.md#recovery-and-failures), the user guide's [store failure section](alpha-testing.md#if-the-local-store-fails), and the lifecycle tests |
| Redaction tests (required tests) | Domain primitive and validation tests, the inventory adapter test and the built-CLI test in `scripts/tests/cli-smoke.test.mjs` |

Work packages moved to the phase that first needs them, so no port exists without a caller: the filesystem inventory port and scan repositories (Phase 3), scan lifecycle events and event publication (Phase 5), and the provider port (Phase 9). Browser launch stays in `apps/cli` until the server moves out of it (ADR 0005 debt).

### Goal

Expand Down
13 changes: 13 additions & 0 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,19 @@ The local SQLite store ([ADR 0006](decisions/0006-local-store-node-sqlite.md)) l

It never contains source file contents. It is not synchronized or exported, and the API never returns root paths. Session routes require the local session capability. Mutations also require a same-origin `Origin` header, a JSON content type and a body under 300,000 bytes. Users can delete the directory to remove all stored data.

## Redaction at the discovery boundary

Text read from analyzed manifests (package and dependency names) is untrusted. Before it reaches the graph, the store, the API or any output, the CLI inventory:
- replaces known secret shapes with `[redacted]`, removing the whole token (a private-key block up to its end marker, a JWT including its signature);
- replaces home directories with `~`: the running user's real home directory, plus the generic `/Users/<name>` and `X:\Users\<name>` shapes;
- repeats until nothing changes, so removing one piece cannot reassemble another.

The `archwise.graph` validator rejects labels that still contain a secret shape or a generic home-directory shape. Linux `/home/<name>` is redacted only for the running user, because route labels such as `/home/feed` share its shape. `--json` and `--graph` output use repository-relative paths and never print the absolute workspace root. Directory names are not redacted: a directory named like a secret appears in evidence paths, and the graph validator then rejects that revision, so sessions are not saved for that run.

Tests cover the domain primitives and validation, the inventory adapter, and the built CLI output.

Pattern matching is defense in depth. It does not prove that text is free of sensitive data.

## Secret handling

Archwise inventories the existence of sensitive configuration only when useful; it does not read `.env` values, private keys, credential directories, or known secret files by default. Provider keys live in the OS credential store where supported. Diagnostic bundles require preview and explicit export, with a second redaction pass.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The JSON importer accepts text up to 16 MiB measured as UTF-8 before parsing. Li

Canonical serialization uses explicit object field order, sorts record collections by ID, coverage by repository/analyzer/version, and set-like reference/reason lists by ASCII code-unit order. Reject duplicate coverage keys and duplicate reference/reason entries. Do not use locale-sensitive sorting. Emit compact JSON without a trailing newline; preserve Unicode label spelling. Same logical revision, IDs, timestamp and schema version must produce identical UTF-8 bytes regardless of input collection order or OS.

Serialization validates again and includes only declared portable fields. Labels and paths remain untrusted strings: reject control characters and known secret-value patterns before export, and test synthetic credential examples. This is defense in depth, not proof that arbitrary labels contain no sensitive information. A later user-facing export flow must offer review; documentation must not claim perfect secret detection. No source content or absolute-root field is accepted by the format.
Serialization validates again and includes only declared portable fields. Labels and paths remain untrusted strings: reject control characters and known secret-value patterns before export, and test synthetic credential examples. Amendment (2026-11-16, Phase 2 redaction): labels with a generic home-directory shape, `/Users/<name>` (case-sensitive) or `X:\Users\<name>`, are rejected as `home-path`. Linux `/home/<name>` and `/root` are not rejected by the format, because route labels such as `/home/feed` share that shape; adapters redact the running user's actual home directory instead. This is defense in depth, not proof that arbitrary labels contain no sensitive information. A later user-facing export flow must offer review; documentation must not claim perfect secret detection. No source content or absolute-root field is accepted by the format.

## Sandbox boundary

Expand Down
4 changes: 2 additions & 2 deletions packages/domain/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
Pure graph contracts with no runtime dependencies, filesystem, clock or randomness.

- `graph.ts`: the `archwise.graph` v1 vocabulary. It covers repositories, evidence, analyzer coverage, nodes, edges, diagnostics, `GraphRevision` and the safety `LIMITS`.
- `primitives.ts`: validators for IDs, codes, labels, timestamps and relative paths, known secret-pattern detection, and code-unit ordering.
- `primitives.ts`: validators for IDs, codes, labels, timestamps and relative paths, known secret-pattern and home-directory detection, `redactSensitiveText` for adapters, and code-unit ordering.
- `validation.ts`: `validateRevision` returns stable error codes with structural paths and never echoes rejected values.
- `revision.ts`: `createRevision` copies the input, validates it and returns a canonical, deeply frozen revision. `canonicalizeRevision` applies the deterministic ordering.
- `sandbox.ts`: `bindSandbox` checks that a readonly sandbox reference matches its base revision. Operation logs are not part of this package yet.

Secret-pattern checks are defense in depth, not proof that a label or path contains no sensitive data.
Labels that contain a known secret shape (`secret-pattern`) or a generic home-directory path, `/Users/<name>` or `C:\Users\<name>` (`home-path`), are rejected. `redactSensitiveText` also accepts the running user's home directories, so adapters can redact Linux homes without flagging route labels such as `/home/feed`. These checks are defense in depth, not proof that a label or path contains no sensitive data.

Public exports live in `src/index.ts`. Tests live in `tests/`. Run `pnpm --filter @archwise/domain test` from the root. Build dependencies first with `pnpm build`.
Loading
Loading