@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/utils/mcp-tool-groups.js

@@ -0,0 +1,117 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Which MCP tool groups a workspace exposes, and how that choice is written
+ * into a host configuration file.
+ *
+ * Three places decide this — the MCP server (reading the environment), the CLI
+ * (`devsteps setup --tools`) and the VS Code extension (a workspace setting) —
+ * and a selection that means different things in different hosts would be worse
+ * than no selection at all. The rules therefore live here, once.
+ *
+ * @see STORY-392
+ */
+/**
+ * Environment variable that selects which MCP tool groups the server exposes.
+ *
+ * Every tool schema sits in the agent's context on every request, so a
+ * workspace that never touches the docs or workflow pipeline can drop those
+ * schemas by naming only the groups it uses. Unset means the default catalog.
+ */
+export const MCP_TOOL_GROUP_ENV_VAR = 'DEVSTEPS_MCP_TOOLS';
+/**
+ * Selectable MCP tool groups, in catalog order.
+ *
+ * The membership of each group lives in the MCP server's tool catalog; this
+ * list exists so the CLI and the extension can validate a selection without
+ * depending on the server package. `catalog.test.ts` asserts that both stay in
+ * step, so a new group fails there rather than drifting silently.
+ */
+export const MCP_TOOL_GROUP_NAMES = ['core', 'docs', 'workflow', 'coord', 'batch'];
+/**
+ * Groups a workspace would get only by naming them, left out of an unset selection and `all`.
+ * Batch creation is explicit; existing default catalog profiles remain unchanged.
+ */
+export const MCP_OPT_IN_TOOL_GROUPS = ['batch'];
+/** What an unset selection or `all` exposes: every group that is not opt-in. */
+export const MCP_DEFAULT_TOOL_GROUPS = MCP_TOOL_GROUP_NAMES.filter((name) => !MCP_OPT_IN_TOOL_GROUPS.includes(name));
+/**
+ * The groups a parsed selection activates: the default groups for an unset or `all` selection
+ * (plus the opt-in groups it names), the named groups otherwise, and the defaults when nothing
+ * valid remains, so a typo cannot disarm the server.
+ */
+export function activeToolGroups(selection) {
+    if (!selection.all && selection.groups.length > 0)
+        return selection.groups;
+    const optIn = selection.groups.filter((name) => MCP_OPT_IN_TOOL_GROUPS.includes(name));
+    return MCP_TOOL_GROUP_NAMES.filter((name) => MCP_DEFAULT_TOOL_GROUPS.includes(name) || optIn.includes(name));
+}
+/**
+ * Parse a `DEVSTEPS_MCP_TOOLS` value into a validated selection.
+ *
+ * Comma-separated, order- and case-insensitive. Callers decide what to do with
+ * an unusable selection: the server falls back to the default catalog so a typo
+ * cannot disarm it, while the CLI refuses the write and says what is wrong.
+ */
+export function parseToolGroupSelection(raw) {
+    const requested = (raw ?? '')
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0);
+    const all = requested.length === 0 || requested.includes('all');
+    const known = new Set(MCP_TOOL_GROUP_NAMES);
+    return {
+        groups: MCP_TOOL_GROUP_NAMES.filter((name) => requested.includes(name)),
+        unknown: requested.filter((entry) => entry !== 'all' && !known.has(entry)),
+        all,
+    };
+}
+/**
+ * Turn a raw setting or flag value into a selection.
+ *
+ * `undefined` means not configured. A value that survives parsing with no valid
+ * group left is treated the same way: acting on a typo would rewrite a host
+ * entry for a selection the server would ignore anyway.
+ */
+export function selectToolGroups(raw) {
+    if (raw === undefined || raw.trim().length === 0) {
+        return { selection: { managed: false }, unknown: [] };
+    }
+    const parsed = parseToolGroupSelection(raw);
+    const { groups, unknown, all } = parsed;
+    if (all && !groups.some((name) => MCP_OPT_IN_TOOL_GROUPS.includes(name))) {
+        return { selection: { managed: true }, unknown };
+    }
+    if (all)
+        return { selection: { managed: true, groups: activeToolGroups(parsed).join(',') }, unknown };
+    if (groups.length === 0)
+        return { selection: { managed: false }, unknown };
+    return { selection: { managed: true, groups: groups.join(',') }, unknown };
+}
+/** The `env` block a selection contributes, empty when the default catalog is active. */
+export function toolGroupEnv(selection) {
+    return selection?.groups ? { env: { [MCP_TOOL_GROUP_ENV_VAR]: selection.groups } } : {};
+}
+/**
+ * Merge a selection into the environment an existing host entry already carries.
+ *
+ * Variables the workspace added itself are kept — a rewrite is triggered by a
+ * changed runtime resolution, which says nothing about the rest of the entry.
+ * The tool-group key is only replaced when the selection manages it; otherwise
+ * a hand-written selection would be discarded without notice.
+ */
+export function mergeToolGroupEnv(existingEnv, selection) {
+    const preserved = {};
+    if (existingEnv && typeof existingEnv === 'object') {
+        for (const [key, value] of Object.entries(existingEnv)) {
+            if (typeof value === 'string')
+                preserved[key] = value;
+        }
+    }
+    if (selection.managed)
+        delete preserved[MCP_TOOL_GROUP_ENV_VAR];
+    const merged = { ...preserved, ...toolGroupEnv(selection).env };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+//# sourceMappingURL=mcp-tool-groups.js.map

package/dist/utils/mcp-tool-groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-groups.js","sourceRoot":"","sources":["../../src/utils/mcp-tool-groups.ts"],"names":[],"mappings":"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"}

package/dist/utils/packaged-github.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Locate the `.github` payload an installed DevSteps package ships.
+ *
+ * An adapter module runs from two layouts: unbundled (`dist/commands/<file>`,
+ * `src/handlers/<file>`) sits two levels below the package root, while an
+ * esbuild bundle (`dist/index.bundled.mjs`) sits one level below it. A fixed
+ * `'..', '..'` lands outside the package in the bundled case, which left `init`
+ * without the contract block and the Copilot tree (BUG-124). The VS Code
+ * extension ships its payload beside its MCP bundle, at `dist/.github` next to
+ * `dist/mcp-server.js`, so the module directory itself is the last candidate
+ * (BUG-140).
+ *
+ * @see STORY-407 BUG-124 TASK-792 BUG-140
+ */
+/**
+ * The packaged `.github` directory for an adapter module located in
+ * `moduleDirectory`, or undefined when the installation ships none.
+ */
+export declare function resolvePackagedGithubDir(moduleDirectory: string): string | undefined;
+//# sourceMappingURL=packaged-github.d.ts.map

package/dist/utils/packaged-github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packaged-github.d.ts","sourceRoot":"","sources":["../../src/utils/packaged-github.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOpF"}

package/dist/utils/packaged-github.js

@@ -0,0 +1,38 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Locate the `.github` payload an installed DevSteps package ships.
+ *
+ * An adapter module runs from two layouts: unbundled (`dist/commands/<file>`,
+ * `src/handlers/<file>`) sits two levels below the package root, while an
+ * esbuild bundle (`dist/index.bundled.mjs`) sits one level below it. A fixed
+ * `'..', '..'` lands outside the package in the bundled case, which left `init`
+ * without the contract block and the Copilot tree (BUG-124). The VS Code
+ * extension ships its payload beside its MCP bundle, at `dist/.github` next to
+ * `dist/mcp-server.js`, so the module directory itself is the last candidate
+ * (BUG-140).
+ *
+ * @see STORY-407 BUG-124 TASK-792 BUG-140
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+function isPackagedGithubDir(directory) {
+    return (existsSync(join(directory, 'copilot-instructions.md')) &&
+        existsSync(join(directory, 'agents')) &&
+        existsSync(join(directory, 'instructions')) &&
+        existsSync(join(directory, 'prompts')));
+}
+/**
+ * The packaged `.github` directory for an adapter module located in
+ * `moduleDirectory`, or undefined when the installation ships none.
+ */
+export function resolvePackagedGithubDir(moduleDirectory) {
+    const candidates = [
+        join(moduleDirectory, '..', '..', '.github'),
+        join(moduleDirectory, '..', '.github'),
+        join(moduleDirectory, '.github'),
+    ];
+    return candidates.find(isPackagedGithubDir);
+}
+//# sourceMappingURL=packaged-github.js.map

package/dist/utils/packaged-github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packaged-github.js","sourceRoot":"","sources":["../../src/utils/packaged-github.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,SAAS,mBAAmB,CAAC,SAAiB;IAC5C,OAAO,CACL,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC,CAAC;QACtD,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACrC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAC3C,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CACvC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;QAC5C,IAAI,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;QACtC,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC;KACjC,CAAC;IACF,OAAO,UAAU,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAC9C,CAAC"}

package/dist/utils/setup-guide.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+/** Render the optional generated setup guide without writing to the filesystem. */
+export declare function renderSetupMd(projectName: string): string;
+//# sourceMappingURL=setup-guide.d.ts.map

package/dist/utils/setup-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-guide.d.ts","sourceRoot":"","sources":["../../src/utils/setup-guide.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgFzD"}

package/dist/utils/setup-guide.js

@@ -0,0 +1,87 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+/** Render the optional generated setup guide without writing to the filesystem. */
+export function renderSetupMd(projectName) {
+    return `# ${projectName} - Setup Guide
+
+## Prerequisites
+
+- Node.js v18+ (https://nodejs.org)
+- Package manager: pnpm (recommended) or npm
+- Git (optional, for version control)
+
+## Quick Start
+
+\`\`\`bash
+# 1. Install dependencies
+pnpm install  # or: npm install
+
+# 2. Verify setup
+devsteps doctor
+
+# 3. Check project status
+devsteps status
+
+# 4. Add your first item
+devsteps add req "Your first requirement"
+\`\`\`
+
+## MCP Setup (AI Integration)
+
+\`\`\`bash
+# For VS Code (auto-detect)
+devsteps setup
+
+# Explicit IDE selection
+devsteps setup --tool vscode
+\`\`\`
+
+After setup: restart your IDE, then open Copilot/AI Chat.
+
+## Project Structure
+
+\`\`\`
+${projectName}/
+├── .devsteps/
+│   ├── config.json       # Project configuration
+│   ├── index/            # Refs-style distributed index
+│   ├── items/            # Item files (source of truth)
+│   └── archive/          # Archived items
+└── .vscode/
+    ├── tasks.json        # VS Code tasks
+    └── mcp.json          # MCP configuration
+\`\`\`
+
+## Common Commands
+
+\`\`\`bash
+# Add items
+devsteps add story "Implement feature X"
+devsteps add bug "Error on page load"
+
+# List & filter
+devsteps list --status draft
+devsteps list --type story --priority urgent-important
+
+# Update
+devsteps update STORY-001 --status in-progress
+
+# Link items
+devsteps link TASK-001 implements STORY-005
+
+# Maintenance
+devsteps archive STORY-001
+devsteps purge --status done
+\`\`\`
+
+## Troubleshooting
+
+- **"Project not initialized"** — run \`devsteps init\` in your project directory
+- **"Node.js version too old"** — upgrade to v18+ from nodejs.org
+- **"MCP server not found"** — run \`devsteps setup\`, then restart your IDE
+- **Dependencies missing** — run \`pnpm install\`
+`;
+}
+//# sourceMappingURL=setup-guide.js.map

package/dist/utils/setup-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-guide.js","sourceRoot":"","sources":["../../src/utils/setup-guide.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO,KAAK,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCvB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCZ,CAAC;AACF,CAAC"}

package/dist/utils/snapshot-manifest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Snapshot byte evidence and recognition; foreign backup trees are never owned.
+ */
+export declare const SNAPSHOT_FORMAT = "devsteps-agent-files-snapshot";
+export interface SnapshotEntry {
+    source: string;
+    file: string;
+    sha256: string;
+    size: number;
+}
+export interface SnapshotManifest {
+    format: typeof SNAPSHOT_FORMAT;
+    schemaVersion: 1;
+    status: 'complete';
+    timestamp: string;
+    completedAt: string;
+    packageVersion: string;
+    workspaceRoot: string;
+    githubDir?: string;
+    files: SnapshotEntry[];
+}
+export declare function byteHash(bytes: Buffer): string;
+/** A descriptor keeps the read on the checked inode and refuses leaf links. */
+export declare function readSnapshotBytes(path: string): Buffer;
+export interface SafeSnapshotTree {
+    files: string[];
+    directories: string[];
+}
+/** Inventory before deletion; a single unexpected link makes the whole tree ineligible. */
+export declare function inspectSnapshotTree(root: string): SafeSnapshotTree;
+/** Recognition is intentionally stricter than checking a directory name or marker. */
+export declare function recognizedSnapshot(root: string, workspaceRoot: string): SafeSnapshotTree;
+//# sourceMappingURL=snapshot-manifest.d.ts.map

package/dist/utils/snapshot-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-manifest.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BtD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAgBlE;AAmBD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,gBAAgB,CAkDxF"}

package/dist/utils/snapshot-manifest.js

@@ -0,0 +1,116 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Snapshot byte evidence and recognition; foreign backup trees are never owned.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { assertSafeDirectory, assertSafeFile, assertUniqueKeys, pathEntry, } from './snapshot-paths.js';
+export const SNAPSHOT_FORMAT = 'devsteps-agent-files-snapshot';
+export function byteHash(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** A descriptor keeps the read on the checked inode and refuses leaf links. */
+export function readSnapshotBytes(path) {
+    const before = assertSafeFile(path);
+    const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fstatSync(descriptor);
+        if (!before ||
+            !opened.isFile() ||
+            opened.nlink !== 1 ||
+            before.dev !== opened.dev ||
+            before.ino !== opened.ino) {
+            throw new Error(`Snapshot source changed while opening: ${path}`);
+        }
+        const bytes = readFileSync(descriptor);
+        const after = fstatSync(descriptor);
+        if (after.size !== opened.size ||
+            after.mtimeMs !== opened.mtimeMs ||
+            after.ctimeMs !== opened.ctimeMs ||
+            after.nlink !== 1 ||
+            bytes.length !== after.size) {
+            throw new Error(`Snapshot source changed while reading: ${path}`);
+        }
+        return bytes;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/** Inventory before deletion; a single unexpected link makes the whole tree ineligible. */
+export function inspectSnapshotTree(root) {
+    const tree = { files: [], directories: [root] };
+    for (let index = 0; index < tree.directories.length; index++) {
+        const directory = tree.directories[index];
+        assertSafeDirectory(directory);
+        for (const name of readdirSync(directory)) {
+            const path = join(directory, name);
+            const entry = pathEntry(path);
+            if (entry?.isDirectory() && !entry.isSymbolicLink())
+                tree.directories.push(path);
+            else {
+                assertSafeFile(path);
+                tree.files.push(path);
+            }
+        }
+    }
+    return tree;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSnapshotEntry(value) {
+    return (isRecord(value) &&
+        typeof value.source === 'string' &&
+        typeof value.file === 'string' &&
+        typeof value.sha256 === 'string' &&
+        /^[a-f0-9]{64}$/.test(value.sha256) &&
+        typeof value.size === 'number' &&
+        Number.isSafeInteger(value.size) &&
+        value.size >= 0);
+}
+/** Recognition is intentionally stricter than checking a directory name or marker. */
+export function recognizedSnapshot(root, workspaceRoot) {
+    const value = JSON.parse(readSnapshotBytes(join(root, 'manifest.json')).toString('utf8'));
+    if (!isRecord(value) ||
+        value.format !== SNAPSHOT_FORMAT ||
+        value.schemaVersion !== 1 ||
+        value.status !== 'complete' ||
+        value.workspaceRoot !== workspaceRoot ||
+        typeof value.timestamp !== 'string' ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}$/.test(value.timestamp) ||
+        !basename(root).startsWith(`github-${value.timestamp}-`) ||
+        typeof value.completedAt !== 'string' ||
+        !Number.isFinite(Date.parse(value.completedAt)) ||
+        !Array.isArray(value.files) ||
+        value.files.length === 0 ||
+        !value.files.every(isSnapshotEntry)) {
+        throw new Error('Unrecognized or incomplete snapshot manifest');
+    }
+    const entries = value.files;
+    assertUniqueKeys(entries.map((entry) => entry.source));
+    assertUniqueKeys(entries.map((entry) => entry.file), true);
+    const tree = inspectSnapshotTree(root);
+    const expected = new Set(['manifest.json', ...entries.map((entry) => entry.file)]);
+    const expectedDirectories = new Set(['']);
+    for (const entry of entries) {
+        const parts = entry.file.split('/');
+        for (let length = 1; length < parts.length; length++) {
+            expectedDirectories.add(parts.slice(0, length).join('/'));
+        }
+        const bytes = readSnapshotBytes(join(root, entry.file));
+        if (bytes.length !== entry.size || byteHash(bytes) !== entry.sha256) {
+            throw new Error(`Snapshot byte evidence does not match: ${entry.file}`);
+        }
+    }
+    if (tree.files.length !== expected.size ||
+        tree.files.some((path) => !expected.has(relative(root, path).split('\\').join('/'))) ||
+        tree.directories.some((path) => !expectedDirectories.has(relative(root, path).split('\\').join('/')))) {
+        throw new Error('Snapshot contains foreign files or directories');
+    }
+    return tree;
+}
+//# sourceMappingURL=snapshot-manifest.js.map

package/dist/utils/snapshot-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-manifest.js","sourceRoot":"","sources":["../../src/utils/snapshot-manifest.ts"],"names":[],"mappings":"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"}

package/dist/utils/snapshot-paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Conservative path and link checks for pre-write snapshots and update targets.
+ */
+import { type Stats } from 'node:fs';
+/** Snapshot keys use one portable spelling on every supported host. */
+export declare function validateSnapshotKey(key: string): void;
+export declare function pathEntry(path: string): Stats | undefined;
+/** Walk every existing ancestor rather than merely resolving links into the workspace. */
+export declare function assertSafeDirectory(path: string, allowMissing?: boolean): void;
+export declare function workspacePath(root: string, key: string): string;
+/** Reject duplicate, case-alias and file/directory prefix mappings. */
+export declare function assertUniqueKeys(keys: readonly string[], reserveManifest?: boolean): void;
+export declare function assertSafeFile(path: string, allowMissing?: boolean): Stats | undefined;
+/** Preflight all overwrite/delete/add targets before any updater mutation. */
+export declare function validateWorkspaceTargets(root: string, keys: readonly string[]): void;
+/** Backup roots may be absent but must remain strictly inside the workspace. */
+export declare function validateBackupsRoot(root: string, devstepsDir: string): string;
+//# sourceMappingURL=snapshot-paths.d.ts.map

package/dist/utils/snapshot-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-paths.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhD,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAqBrD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAOzD;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,IAAI,CAY5E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,eAAe,UAAQ,GAAG,IAAI,CAmBvF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,KAAK,GAAG,SAAS,CAQpF;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAIpF;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ7E"}

package/dist/utils/snapshot-paths.js

@@ -0,0 +1,111 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Conservative path and link checks for pre-write snapshots and update targets.
+ */
+import { lstatSync } from 'node:fs';
+import { dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { validateWorkspacePath } from '../core/path-guard.js';
+/** Snapshot keys use one portable spelling on every supported host. */
+export function validateSnapshotKey(key) {
+    if (!key ||
+        key.includes('\\') ||
+        /[<>:"|?*]/.test(key) ||
+        [...key].some((character) => character.charCodeAt(0) < 32) ||
+        isAbsolute(key)) {
+        throw new Error(`Unsafe snapshot path: ${key}`);
+    }
+    for (const part of key.split('/')) {
+        if (!part ||
+            part === '.' ||
+            part === '..' ||
+            /[. ]$/.test(part) ||
+            /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)) {
+            throw new Error(`Ambiguous snapshot path: ${key}`);
+        }
+    }
+}
+export function pathEntry(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Walk every existing ancestor rather than merely resolving links into the workspace. */
+export function assertSafeDirectory(path, allowMissing = false) {
+    const absolute = resolve(path);
+    const root = parse(absolute).root;
+    let current = root;
+    for (const segment of relative(root, absolute).split(/[\\/]/).filter(Boolean)) {
+        current = join(current, segment);
+        const entry = pathEntry(current);
+        if (!entry && allowMissing)
+            continue;
+        if (!entry || entry.isSymbolicLink() || !entry.isDirectory()) {
+            throw new Error(`Unsafe snapshot directory: ${current}`);
+        }
+    }
+}
+export function workspacePath(root, key) {
+    validateSnapshotKey(key);
+    const target = validateWorkspacePath(key, root);
+    if (!target || target === resolve(root))
+        throw new Error(`Path escapes workspace: ${key}`);
+    return target;
+}
+/** Reject duplicate, case-alias and file/directory prefix mappings. */
+export function assertUniqueKeys(keys, reserveManifest = false) {
+    const claimed = new Set();
+    const sorted = keys
+        .map((key) => {
+        validateSnapshotKey(key);
+        return key.normalize('NFC').toLowerCase();
+    })
+        .sort();
+    if (reserveManifest)
+        sorted.push('manifest.json');
+    for (const key of sorted.sort()) {
+        if (claimed.has(key))
+            throw new Error(`Snapshot path collision: ${key}`);
+        const parts = key.split('/');
+        for (let index = 1; index < parts.length; index++) {
+            if (claimed.has(parts.slice(0, index).join('/'))) {
+                throw new Error(`Snapshot file/directory collision: ${key}`);
+            }
+        }
+        claimed.add(key);
+    }
+}
+export function assertSafeFile(path, allowMissing = false) {
+    assertSafeDirectory(dirname(path), allowMissing);
+    const entry = pathEntry(path);
+    if (!entry && allowMissing)
+        return undefined;
+    if (!entry || entry.isSymbolicLink() || !entry.isFile() || entry.nlink !== 1) {
+        throw new Error(`Unsafe snapshot file (links and non-files are refused): ${path}`);
+    }
+    return entry;
+}
+/** Preflight all overwrite/delete/add targets before any updater mutation. */
+export function validateWorkspaceTargets(root, keys) {
+    assertSafeDirectory(root);
+    assertUniqueKeys(keys);
+    for (const key of keys)
+        assertSafeFile(workspacePath(root, key), true);
+}
+/** Backup roots may be absent but must remain strictly inside the workspace. */
+export function validateBackupsRoot(root, devstepsDir) {
+    assertSafeDirectory(root);
+    const relativeDir = relative(resolve(root), resolve(devstepsDir)).split('\\').join('/');
+    const directory = workspacePath(root, relativeDir);
+    assertSafeDirectory(directory, true);
+    const backupsRoot = join(directory, 'backups');
+    assertSafeDirectory(backupsRoot, true);
+    return backupsRoot;
+}
+//# sourceMappingURL=snapshot-paths.js.map

package/dist/utils/snapshot-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-paths.js","sourceRoot":"","sources":["../../src/utils/snapshot-paths.ts"],"names":[],"mappings":"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"}

package/dist/utils/snapshot-retention.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Retain only recognized complete snapshots, preserving unsafe and foreign entries.
+ */
+import { type Stats } from 'node:fs';
+export declare const BACKUP_DIR_PREFIX = "github-";
+export declare function cleanIncompleteSnapshot(directory: string, owner?: Stats): void;
+/** A retention problem does not invalidate the completed pre-write evidence. */
+export declare function pruneSnapshots(backupsRoot: string, fresh: string, workspaceRoot: string, maxBackups: number): string[];
+//# sourceMappingURL=snapshot-retention.d.ts.map

package/dist/utils/snapshot-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-retention.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-retention.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA0B,KAAK,KAAK,EAAc,MAAM,SAAS,CAAC;AASzE,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAe3C,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAY9E;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CA8BV"}