@webpresso/agent-kit 0.21.0

package/dist/esm/dev/dev-link-state.js

@@ -0,0 +1,51 @@
+/**
+ * Shared types + I/O for `<consumer>/.webpresso/webpresso-dev-link.json`.
+ *
+ * Single source of truth for the dev-link state file format used by:
+ *   - `scripts/link-edge-local.ts` — writes the file when `--consumer` is passed
+ *   - `src/hooks/check-dev-link/index.ts` — SessionStart hook reads it
+ *   - `src/dev/restore-dev-links/index.ts` — postinstall bin reads it
+ *
+ * The file is gitignored on the consumer side (per-developer dev opt-in);
+ * its absence means CI / no-dev-link path → all readers no-op silently.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const STATE_FILE_RELATIVE_PATH = '.webpresso/webpresso-dev-link.json';
+/**
+ * Read + validate the dev-link state file from a consumer's repo root.
+ *
+ * Returns `null` when:
+ *   - the file is absent (CI / never linked) — silent no-op path
+ *   - the file is malformed JSON — degrade gracefully, never crash callers
+ *   - required fields (`package`, `linkedFrom`) are missing or wrong type
+ *
+ * Callers MUST treat `null` as "no dev-link active" and proceed silently.
+ * Callers that need fail-loud semantics on degraded state (e.g. the postinstall
+ * restore bin) should layer their own error handling on top.
+ */
+export function readDevLinkState(consumerCwd) {
+    const path = join(consumerCwd, STATE_FILE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const candidate = raw;
+    if (typeof candidate.package !== 'string' || candidate.package === '')
+        return null;
+    if (typeof candidate.linkedFrom !== 'string' || candidate.linkedFrom === '')
+        return null;
+    return {
+        package: candidate.package,
+        linkedFrom: candidate.linkedFrom,
+        linkedAt: typeof candidate.linkedAt === 'string' ? candidate.linkedAt : undefined,
+        webpressoVersion: typeof candidate.webpressoVersion === 'string' ? candidate.webpressoVersion : undefined,
+        note: typeof candidate.note === 'string' ? candidate.note : undefined,
+    };
+}
+//# sourceMappingURL=dev-link-state.js.map

package/dist/esm/dev/index.d.ts

@@ -0,0 +1,2 @@
+export { type AkDevManifest, type AkDevMode, type AkDevService, type ResolveManifestInput, type ResolvedManifest, loadDevManifest, resolveDevServices, resolveManifestPath, } from './load-manifest.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/dev/index.js

@@ -0,0 +1,2 @@
+export { loadDevManifest, resolveDevServices, resolveManifestPath, } from './load-manifest.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/dev/load-manifest.d.ts

@@ -0,0 +1,35 @@
+export type AkDevMode = 'start' | 'doctor' | 'clean' | 'restart';
+export interface AkDevService {
+    id: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    env: Record<string, string>;
+    dependsOn: string[];
+    readiness?: unknown;
+    restart?: unknown;
+}
+export interface AkDevManifest {
+    version: 1;
+    services: Record<string, AkDevService>;
+    groups: Record<string, {
+        services: string[];
+        description?: string;
+    }>;
+    defaults: {
+        target?: string;
+    };
+}
+export interface ResolveManifestInput {
+    cwd?: string;
+    manifestPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ResolvedManifest {
+    manifestPath: string;
+    manifest: AkDevManifest;
+}
+export declare function resolveManifestPath(input?: ResolveManifestInput): string;
+export declare function loadDevManifest(input?: ResolveManifestInput): ResolvedManifest;
+export declare function resolveDevServices(manifest: AkDevManifest, target?: string | undefined): string[];
+//# sourceMappingURL=load-manifest.d.ts.map

package/dist/esm/dev/load-manifest.js

@@ -0,0 +1,182 @@
+import matter from 'gray-matter';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+export function resolveManifestPath(input = {}) {
+    const cwd = input.cwd ?? process.cwd();
+    const env = input.env ?? process.env;
+    const candidates = [
+        input.manifestPath,
+        env.WP_APP_MANIFEST,
+        join(cwd, 'app-manifest.yaml'),
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        const absolute = isAbsolute(candidate) ? candidate : resolve(cwd, candidate);
+        if (existsSync(absolute))
+            return absolute;
+    }
+    throw new Error('Unable to find dev manifest. Checked --manifest, WP_APP_MANIFEST, and ./app-manifest.yaml.');
+}
+export function loadDevManifest(input = {}) {
+    const manifestPath = resolveManifestPath(input);
+    const raw = readFileSync(manifestPath, 'utf-8');
+    const parsed = parseManifestContent(raw, manifestPath);
+    return {
+        manifestPath,
+        manifest: normalizeManifest(parsed),
+    };
+}
+export function resolveDevServices(manifest, target = manifest.defaults.target) {
+    if (!target) {
+        throw new Error('No dev target supplied and defaults.target is not configured');
+    }
+    const roots = manifest.groups[target]?.services ?? (manifest.services[target] ? [target] : undefined);
+    if (!roots) {
+        throw new Error(`Unknown dev target "${target}". Known services: ${Object.keys(manifest.services).join(', ')}. Known groups: ${Object.keys(manifest.groups).join(', ')}.`);
+    }
+    const out = [];
+    const visited = new Set();
+    const visiting = new Set();
+    function visit(id, stack) {
+        if (visited.has(id))
+            return;
+        if (visiting.has(id)) {
+            const cycleStart = stack.indexOf(id);
+            throw new Error(`Cyclic dev service dependency detected: ${[...stack.slice(cycleStart), id].join(' -> ')}`);
+        }
+        const service = manifest.services[id];
+        if (!service)
+            throw new Error(`Unknown dev service "${id}"`);
+        visiting.add(id);
+        for (const dependency of service.dependsOn) {
+            visit(dependency, [...stack, id]);
+        }
+        visiting.delete(id);
+        visited.add(id);
+        out.push(id);
+    }
+    for (const root of roots)
+        visit(root, []);
+    return out;
+}
+function parseManifestContent(raw, manifestPath) {
+    if (manifestPath.endsWith('.json')) {
+        return JSON.parse(raw);
+    }
+    return matter(`---\n${raw}\n---\n`).data;
+}
+function normalizeManifest(raw) {
+    const input = assertRecord(raw, 'dev manifest');
+    if (input.version !== 1)
+        throw new Error('dev manifest version must be 1');
+    const rawServices = assertRecord(input.services, 'services');
+    const services = {};
+    for (const [id, serviceRaw] of Object.entries(rawServices)) {
+        const service = assertRecord(serviceRaw, `services.${id}`);
+        const command = normalizeCommand(service, `services.${id}`);
+        services[id] = {
+            id,
+            command: command.command,
+            args: command.args ?? assertStringArray(service.args ?? [], `services.${id}.args`),
+            env: service.env ? normalizeEnvRecord(service.env, `services.${id}.env`) : {},
+            dependsOn: assertStringArray(service.dependsOn ?? [], `services.${id}.dependsOn`),
+            ...((command.cwd ?? service.cwd)
+                ? { cwd: assertString(command.cwd ?? service.cwd, `services.${id}.cwd`) }
+                : {}),
+            ...(service.readiness ? { readiness: service.readiness } : {}),
+            ...(service.restart ? { restart: service.restart } : {}),
+        };
+    }
+    for (const [id, service] of Object.entries(services)) {
+        for (const dependency of service.dependsOn) {
+            if (!services[dependency]) {
+                throw new Error(`services.${id}.dependsOn references unknown service "${dependency}"`);
+            }
+        }
+    }
+    const groups = {};
+    const rawGroups = input.groups ? assertRecord(input.groups, 'groups') : {};
+    for (const [id, groupRaw] of Object.entries(rawGroups)) {
+        const group = assertRecord(groupRaw, `groups.${id}`);
+        const groupServices = assertStringArray(group.services, `groups.${id}.services`);
+        for (const serviceId of groupServices) {
+            if (!services[serviceId]) {
+                throw new Error(`groups.${id}.services references unknown service "${serviceId}"`);
+            }
+        }
+        groups[id] = {
+            services: groupServices,
+            ...(group.description
+                ? { description: assertString(group.description, `groups.${id}.description`) }
+                : {}),
+        };
+    }
+    const defaultsRaw = input.defaults ? assertRecord(input.defaults, 'defaults') : {};
+    const target = defaultsRaw.target
+        ? assertString(defaultsRaw.target, 'defaults.target')
+        : undefined;
+    if (target && !services[target] && !groups[target]) {
+        throw new Error(`defaults.target references unknown target "${target}"`);
+    }
+    return {
+        version: 1,
+        services,
+        groups,
+        defaults: target ? { target } : {},
+    };
+}
+function assertRecord(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${label} must be an object`);
+    }
+    return value;
+}
+function assertString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function assertStringArray(value, label) {
+    if (!Array.isArray(value))
+        throw new TypeError(`${label} must be an array of strings`);
+    return value.map((entry, index) => assertString(entry, `${label}[${index}]`));
+}
+function normalizeEnvRecord(value, label) {
+    const record = assertRecord(value, label);
+    const out = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (typeof entry === 'string' && entry.trim() !== '') {
+            out[key] = entry;
+        }
+    }
+    return out;
+}
+function normalizeCommand(service, label) {
+    if (typeof service.command === 'string' && service.command.trim() !== '') {
+        return { command: service.command };
+    }
+    if (service.command && typeof service.command === 'object' && !Array.isArray(service.command)) {
+        const commandConfig = service.command;
+        const kind = typeof commandConfig.kind === 'string' ? commandConfig.kind : undefined;
+        const packageName = typeof service.package === 'string' && service.package.trim() !== ''
+            ? service.package
+            : undefined;
+        const cwd = typeof service.cwd === 'string' && service.cwd.trim() !== '' ? service.cwd : undefined;
+        if (kind === 'package-dev' && packageName) {
+            return {
+                command: 'pnpm',
+                args: ['--filter', packageName, 'run', 'dev'],
+                ...(cwd ? { cwd } : {}),
+            };
+        }
+        if (kind === 'wrangler-dev') {
+            return {
+                command: 'wrangler',
+                args: ['dev'],
+                ...(cwd ? { cwd } : {}),
+            };
+        }
+    }
+    throw new TypeError(`${label}.command must be a non-empty string`);
+}
+//# sourceMappingURL=load-manifest.js.map

package/dist/esm/dev/restore-dev-links/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+export type RestoreOutcome = {
+    kind: 'no-state-file';
+} | {
+    kind: 'invalid-state-file';
+    reason: string;
+} | {
+    kind: 'source-missing';
+    expectedSource: string;
+} | {
+    kind: 'already-linked';
+    target: string;
+    source: string;
+} | {
+    kind: 'relinked';
+    target: string;
+    source: string;
+    previous: string | null;
+};
+export interface RestoreOptions {
+    cwd?: string;
+    stdout?: Pick<typeof process.stdout, 'write'>;
+    stderr?: Pick<typeof process.stderr, 'write'>;
+}
+export interface RestoreResult {
+    exitCode: number;
+    outcomes: RestoreOutcome[];
+}
+export declare function restoreDevLinks(options?: RestoreOptions): RestoreResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/dev/restore-dev-links/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+/**
+ * Postinstall helper: restore the webpresso dev-link symlink
+ * that `vp install` overwrites with the pnpm-store snapshot.
+ *
+ * Behavior:
+ *   - State file absent           → silent exit 0 (CI / never linked)
+ *   - State file present + source exists → re-create symlink, log loud
+ *   - State file present + source missing → exit 1 with loud stderr
+ *
+ * No silent fallback to stale code — root-cause fix only. Consumer wires
+ * this into their postinstall script:
+ *
+ *   "scripts": {
+ *     "postinstall": "wp-restore-dev-links && <other postinstall steps>"
+ *   }
+ *
+ * Reasoning for postinstall (not pnpm.overrides + link:): pnpm bakes overrides
+ * into the lockfile, so a conditional `link:` would force --frozen-lockfile
+ * to fail in CI. Postinstall is the only seam that runs deterministically
+ * after install, doesn't touch the lockfile, and is observable enough to debug.
+ */
+import { lstatSync, mkdirSync, readlinkSync, realpathSync, renameSync, symlinkSync, unlinkSync, } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_FILE_RELATIVE_PATH, readDevLinkState } from '#dev/dev-link-state';
+export function restoreDevLinks(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const state = readDevLinkState(cwd);
+    if (state === null) {
+        // Either absent OR malformed. We treat both as "no dev-link active" for the
+        // restore path because acting on a malformed file is more dangerous than
+        // ignoring it. The check-dev-link SessionStart hook will still surface
+        // breakage to the operator at next session start.
+        return { exitCode: 0, outcomes: [{ kind: 'no-state-file' }] };
+    }
+    const target = join(cwd, 'node_modules', state.package);
+    const source = state.linkedFrom;
+    if (!existsSync(join(source, 'package.json'))) {
+        stderr.write(`wp-restore-dev-links: state file points at ${source} but no package.json found there.\n` +
+            `  → Move the webpresso checkout back, or delete ${STATE_FILE_RELATIVE_PATH} to opt out.\n`);
+        return {
+            exitCode: 1,
+            outcomes: [{ kind: 'source-missing', expectedSource: source }],
+        };
+    }
+    const outcome = ensureSymlink(target, source);
+    if (outcome.kind === 'already-linked') {
+        stdout.write(`wp-restore-dev-links: ${state.package} → ${source} (already linked)\n`);
+    }
+    else {
+        const previousLabel = outcome.previous ?? '<store snapshot>';
+        stdout.write(`wp-restore-dev-links: ${state.package} → ${source} (was ${previousLabel})\n`);
+    }
+    return { exitCode: 0, outcomes: [outcome] };
+}
+function ensureSymlink(target, source) {
+    mkdirSync(dirname(target), { recursive: true });
+    let previous = null;
+    if (lstatExists(target)) {
+        const stat = lstatSync(target);
+        if (stat.isSymbolicLink()) {
+            const current = readlinkSync(target);
+            if (current === source) {
+                return { kind: 'already-linked', target, source };
+            }
+            previous = current;
+            unlinkSync(target);
+        }
+        else {
+            const backup = `${target}.store-snapshot.${timestamp()}`;
+            renameSync(target, backup);
+            previous = backup;
+        }
+    }
+    symlinkSync(source, target, 'dir');
+    return { kind: 'relinked', target, source, previous };
+}
+function lstatExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+function timestamp() {
+    const d = new Date();
+    return `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
+}
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    const result = restoreDevLinks();
+    process.exit(result.exitCode);
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/docs-linter/blueprint-plan.d.ts

@@ -0,0 +1,80 @@
+import type { ValidationError } from './types.js';
+/**
+ * Result of finding wrong task headers.
+ */
+interface WrongTaskHeaderResult {
+    count: number;
+    firstLineNumber: number | null;
+}
+/**
+ * Find tasks using ### (3 hashes) instead of #### (4 hashes).
+ * Exported for testability.
+ */
+export declare function findWrongTaskHeaders(content: string): WrongTaskHeaderResult;
+/**
+ * Find malformed task IDs (#### Task without X.Y format).
+ * Exported for testability.
+ */
+export declare function findMalformedTaskIds(content: string): number;
+/**
+ * Result of checking dependency format.
+ */
+interface DependencyCheckResult {
+    hasBareReferences: boolean;
+    exampleLine: string | null;
+}
+/**
+ * Check if dependencies use bare "X.Y" instead of "Task X.Y".
+ * Exported for testability.
+ */
+export declare function checkDependencyFormat(content: string): DependencyCheckResult;
+/**
+ * Extract frontmatter from document content.
+ * Exported for testability.
+ */
+export declare function extractFrontmatter(content: string): Record<string, string> | null;
+/**
+ * Detect if plan is completed based on frontmatter and file path.
+ * Exported for testability.
+ */
+export declare function isCompleted(filePath: string, content: string): boolean;
+/**
+ * Extract complexity from frontmatter, defaulting to 'M'.
+ * Exported for testability.
+ */
+export declare function extractComplexity(content: string): string;
+/**
+ * Check if Completion Summary section exists.
+ * Exported for testability.
+ */
+export declare function hasCompletionSummary(content: string): boolean;
+/**
+ * Extract Lessons Learned content from document.
+ * Returns null if section not found, otherwise returns content after heading.
+ * Exported for testability.
+ */
+export declare function extractLessonsLearnedContent(content: string): string | null;
+/**
+ * Validate Lessons Learned content length (≥50 non-whitespace chars).
+ * Exported for testability.
+ */
+export declare function validateLessonsLearnedContent(content: string | null): boolean;
+/**
+ * Check if Lessons Learned appears after Completion Summary.
+ * Exported for testability.
+ */
+export declare function validateLessonsLearnedPlacement(content: string): boolean;
+/**
+ * Validate Blueprint plan format for implementation plans.
+ *
+ * Only runs on files with doc type `blueprint`.
+ * Returns array of validation errors found.
+ *
+ * @param filePath - File path for error reporting
+ * @param content - File content to validate
+ * @param docType - Document type from frontmatter
+ * @returns Array of validation errors (empty if valid)
+ */
+export declare function validateBlueprintPlan(filePath: string, content: string, docType: string): ValidationError[];
+export {};
+//# sourceMappingURL=blueprint-plan.d.ts.map