freeharness 0.4.1

package/node_modules/@freeharness/sdd/dist/src/bin/openspec.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Store-free, PATH-free `openspec` CLI shim for FreeHarness.
+//
+// A commander-free argv parser dispatching the subcommands the /opsx skills
+// shell out to, over the vendored engine + validation slices. It matches
+// upstream's flags and single-document `--json` output contract so the skills
+// parse it unchanged. Subcommands that were dropped with the store (feedback,
+// store ...) are not registered; `archive` is present but deferred (see
+// src/shim/archive.ts).
+//
+// Root resolution is store-free: walk up from the cwd to the nearest openspec/
+// directory (src/root-resolver.ts). Its PARENT is the project root passed to the
+// engine. `context` may run without a root (to report no_openspec_root); `new
+// change` falls back to the cwd as an implicit root; every other command
+// requires a root.
+import * as path from 'node:path';
+import { findOpenspecDir } from '../root-resolver.js';
+import { statusHandler } from '../shim/status.js';
+import { schemasHandler } from '../shim/schemas.js';
+import { listHandler } from '../shim/list.js';
+import { instructionsHandler } from '../shim/instructions.js';
+import { contextHandler } from '../shim/context.js';
+import { validateHandler } from '../shim/validate.js';
+import { newChangeHandler } from '../shim/new-change.js';
+import { archiveHandler } from '../shim/archive.js';
+import { followUpAddHandler, followUpClaimHandler, followUpListHandler } from '../shim/follow-up.js';
+/** Flags that consume the following token as their value. */
+const VALUE_FLAGS = new Set(['--change', '--schema', '--description', '--sort', '--store', '--type', '--from', '--by']);
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            if (eq !== -1) {
+                flags[token.slice(0, eq)] = token.slice(eq + 1);
+            }
+            else if (VALUE_FLAGS.has(token)) {
+                flags[token] = argv[++i] ?? '';
+            }
+            else {
+                flags[token] = true;
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { positionals, flags };
+}
+function projectRootFrom(startDir) {
+    const openspecDir = findOpenspecDir(startDir);
+    return openspecDir ? path.dirname(openspecDir) : null;
+}
+function requireRoot(cwd) {
+    const root = projectRootFrom(cwd);
+    if (!root) {
+        throw new Error('No OpenSpec root found. Run this inside a project with an openspec/ directory.');
+    }
+    return root;
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const cwd = process.cwd();
+    if (!command || command === '--help' || command === '-h') {
+        printUsage();
+        return command ? 0 : 1;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log('freeharness-sdd-shim');
+        return 0;
+    }
+    const { positionals, flags } = parseArgs(rest);
+    const json = flags['--json'] === true;
+    switch (command) {
+        case 'status':
+            return statusHandler(requireRoot(cwd), {
+                change: flags['--change'],
+                schema: flags['--schema'],
+                json,
+            });
+        case 'instructions':
+            return instructionsHandler(requireRoot(cwd), positionals[0], {
+                change: flags['--change'],
+                schema: flags['--schema'],
+                json,
+            });
+        case 'schemas':
+            return schemasHandler(projectRootFrom(cwd) ?? '', { json });
+        case 'list':
+            return await listHandler(requireRoot(cwd), {
+                json,
+                sort: flags['--sort'] ?? 'recent',
+            });
+        case 'context':
+            return contextHandler(projectRootFrom(cwd), { json });
+        case 'validate':
+            return await validateHandler(requireRoot(cwd), positionals[0], {
+                specs: flags['--specs'] === true,
+                strict: flags['--strict'] === true,
+                json,
+            });
+        case 'new': {
+            // `openspec new change <id>`
+            if (positionals[0] !== 'change') {
+                throw new Error(`Unknown subcommand 'new ${positionals[0] ?? ''}'. Did you mean 'new change <id>'?`);
+            }
+            const root = projectRootFrom(cwd) ?? cwd; // implicit root: scaffold under cwd
+            return newChangeHandler(root, positionals[1], {
+                schema: flags['--schema'],
+                description: flags['--description'],
+                json,
+            });
+        }
+        case 'archive':
+            return await archiveHandler(requireRoot(cwd), positionals[0], {
+                json,
+                yes: flags['--yes'] === true,
+                force: flags['--force'] === true,
+            });
+        case 'follow-up': {
+            const root = requireRoot(cwd);
+            const sub = positionals[0];
+            const options = { json, from: flags['--from'], by: flags['--by'] };
+            if (sub === 'add')
+                return followUpAddHandler(root, positionals[1], positionals[2], options);
+            if (sub === 'list')
+                return followUpListHandler(root, options);
+            if (sub === 'claim')
+                return followUpClaimHandler(root, positionals[1], positionals[2], options);
+            throw new Error(`Unknown subcommand 'follow-up ${sub ?? ''}'. Did you mean 'follow-up add|list|claim'?`);
+        }
+        default:
+            console.error(`Unknown command '${command}'.`);
+            printUsage();
+            return 1;
+    }
+}
+function printUsage() {
+    console.error([
+        'Usage: openspec <command> [options]',
+        '',
+        'Commands:',
+        '  status --change <id> [--schema <s>] [--json]',
+        '  instructions <artifact|apply|archive> --change <id> [--schema <s>] [--json]',
+        '  new change <id> [--schema <s>] [--description <d>] [--json]',
+        '  list [--sort recent|name] [--json]',
+        '  validate [<item>] [--specs] [--strict] [--json]',
+        '  schemas [--json]',
+        '  context [--json]',
+        '  archive <id> [--yes] [--force] [--json]',
+        '  follow-up add <change-id> "<text>" [--from <task>] [--json]',
+        '  follow-up list [--json]',
+        '  follow-up claim <change-id> <index> --by <change-id> [--json]',
+    ].join('\n'));
+}
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/node_modules/@freeharness/sdd/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @freeharness/sdd public surface.
+ *
+ * Store-free, PATH-free vendored slice of OpenSpec: schema validation, project
+ * root resolution, and non-interactive project initialization (the `/opsx`
+ * commands + `openspec-*` skills + `openspec/` scaffold).
+ */
+export { findOpenspecDir } from './root-resolver.js';
+export { validateSchema } from './validate.js';
+export type { ValidateSchemaOptions, ValidateSchemaResult } from './validate.js';
+export { initProject } from './init.js';
+export type { InitProjectOptions, InitProjectResult, SddInitTarget, } from './init.js';
+export { validateChange } from './validate-change.js';
+export type { ValidateChangeOptions, ValidateChangeResult, } from './validate-change.js';

package/node_modules/@freeharness/sdd/dist/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * @freeharness/sdd public surface.
+ *
+ * Store-free, PATH-free vendored slice of OpenSpec: schema validation, project
+ * root resolution, and non-interactive project initialization (the `/opsx`
+ * commands + `openspec-*` skills + `openspec/` scaffold).
+ */
+export { findOpenspecDir } from './root-resolver.js';
+export { validateSchema } from './validate.js';
+export { initProject } from './init.js';
+export { validateChange } from './validate-change.js';

package/node_modules/@freeharness/sdd/dist/src/init.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Store-free, non-interactive `openspec init` for FreeHarness.
+ *
+ * Reconstructs the minimal subset of OpenSpec's `InitCommand.execute` needed to
+ * produce, with NO global `openspec` on PATH, the same on-disk layout that
+ * `openspec init --tools <tool>` writes for Claude Code and OpenCode:
+ *
+ *   - `/opsx` command files      (via the vendored command-generation adapters)
+ *   - `openspec-*` skill files   (via the vendored skill-generation + templates)
+ *   - the `openspec/` project     (specs/, changes/, changes/archive/, config.yaml)
+ *
+ * What was deliberately dropped vs. upstream init.ts (all of it is interactive,
+ * store-, telemetry-, migration-, or multi-tool-selection machinery that has no
+ * place in a library call): tool selection prompts, legacy-artifact cleanup,
+ * store pointer guards, profile/delivery config resolution, GitHub Copilot cloud
+ * files, welcome animation, and success reporting. The generation logic itself
+ * is the vendored upstream code, used faithfully.
+ */
+export type SddInitTarget = 'claude' | 'opencode';
+export interface InitProjectOptions {
+    /** Which harness to generate commands + skills for. */
+    target: SddInitTarget;
+    /** Project root the `openspec/` tree and tool dirs are written under. */
+    projectDir: string;
+}
+export interface InitProjectResult {
+    /** Absolute paths of every file created, in write order. */
+    written: string[];
+    /**
+     * Human-readable notes about files deliberately left untouched (an existing
+     * `openspec/config.yaml`). Callers surface them as `note:` lines.
+     */
+    notes: string[];
+}
+/**
+ * Generates the `/opsx` commands, `openspec-*` skills, and `openspec/` project
+ * structure for one harness under `projectDir`.
+ */
+export declare function initProject(opts: InitProjectOptions): Promise<InitProjectResult>;

package/node_modules/@freeharness/sdd/dist/src/init.js

@@ -0,0 +1,190 @@
+/**
+ * Store-free, non-interactive `openspec init` for FreeHarness.
+ *
+ * Reconstructs the minimal subset of OpenSpec's `InitCommand.execute` needed to
+ * produce, with NO global `openspec` on PATH, the same on-disk layout that
+ * `openspec init --tools <tool>` writes for Claude Code and OpenCode:
+ *
+ *   - `/opsx` command files      (via the vendored command-generation adapters)
+ *   - `openspec-*` skill files   (via the vendored skill-generation + templates)
+ *   - the `openspec/` project     (specs/, changes/, changes/archive/, config.yaml)
+ *
+ * What was deliberately dropped vs. upstream init.ts (all of it is interactive,
+ * store-, telemetry-, migration-, or multi-tool-selection machinery that has no
+ * place in a library call): tool selection prompts, legacy-artifact cleanup,
+ * store pointer guards, profile/delivery config resolution, GitHub Copilot cloud
+ * files, welcome animation, and success reporting. The generation logic itself
+ * is the vendored upstream code, used faithfully.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { generateCommands, CommandAdapterRegistry, } from '../vendor/openspec/generation/command-generation/index.js';
+import { getInvocationForAdapter, needsInvocationRewrite, } from '../vendor/openspec/generation/command-generation/invocation.js';
+import { transformCommandInvocations } from '../vendor/openspec/generation/command-references.js';
+import { getSkillTemplates, getCommandContents, generateSkillContent, } from '../vendor/openspec/generation/shared/skill-generation.js';
+/**
+ * The "core" profile workflow set, mirrored from OpenSpec's
+ * `profiles.ts#CORE_WORKFLOWS`. This is the default set `openspec init` installs
+ * when no custom profile is configured. Inlined rather than vendoring the whole
+ * profile/global-config stack, which is pure interactive-config plumbing.
+ */
+const CORE_WORKFLOWS = [
+    'propose',
+    'explore',
+    'apply',
+    'update',
+    'sync',
+    'archive',
+];
+/**
+ * Project-local skills root per target. Mirrors OpenSpec's `AI_TOOLS[].skillsDir`
+ * for these two tools; skills live under `<skillsDir>/skills/` per the Agent
+ * Skills spec (see resolveToolSkillsDir upstream).
+ */
+const TOOL_SKILLS_DIR = {
+    claude: '.claude',
+    opencode: '.opencode',
+};
+/**
+ * Version stamped into each SKILL.md `generatedBy` field. Upstream reads its own
+ * package.json; here it records the OpenSpec release this generation slice was
+ * vendored from, so the provenance stays honest.
+ */
+const OPENSPEC_VENDOR_VERSION = '1.8.0';
+/**
+ * Minimal reconstruction of OpenSpec's `serializeConfig({ schema })` — the
+ * `openspec/config.yaml` current init writes. Pure string building, so it is
+ * reproduced here rather than vendoring config-prompts.ts and its dependencies.
+ */
+function serializeConfig(schema) {
+    return ([
+        `schema: ${schema}`,
+        '',
+        '# Project context (optional)',
+        '# This is shown to AI when creating artifacts.',
+        '# Add your tech stack, conventions, style guides, domain knowledge, etc.',
+        '# Example:',
+        '#   context: |',
+        '#     Tech stack: TypeScript, React, Node.js',
+        '#     We use conventional commits',
+        '#     Domain: e-commerce platform',
+        '',
+        '# Per-artifact rules (optional)',
+        '# Add custom rules for specific artifacts.',
+        '# Example:',
+        '#   rules:',
+        '#     proposal:',
+        '#       - Keep proposals under 500 words',
+        '#       - Always include a "Non-goals" section',
+        '#     tasks:',
+        '#       - Break tasks into chunks of max 2 hours',
+        '',
+        '# Per-operation guidance (optional)',
+        '# Add advisory guidance for how apply and archive work should be conducted.',
+        '# This is separate from artifact rules above.',
+        '# Example:',
+        '#   operations:',
+        '#     apply:',
+        '#       guidance:',
+        '#         - Keep test summaries concise',
+        '#     archive:',
+        '#       guidance:',
+        '#         - Summarize the archive outcome before finishing',
+    ].join('\n') + '\n');
+}
+/** True when `filePath` exists (any kind of entry). */
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Writes `content` to `filePath`, creating parent directories as needed. */
+async function writeFileEnsuringDir(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf8');
+}
+/**
+ * Hides a generated OpenSpec skill from Claude Code's "/" menu.
+ *
+ * The `openspec-*` skills are the bodies behind the `/opsx:*` commands; the commands
+ * invoke them through the model, so `user-invocable: false` (Claude Code docs, "Control
+ * who invokes a skill") removes the duplicate-looking `/openspec-*` entries from the menu
+ * without changing what the model can call. Other targets are left untouched.
+ *
+ * Args:
+ *   content: The generated SKILL.md text (frontmatter first).
+ *   target: The harness the skill is generated for.
+ *
+ * Returns:
+ *   The content with the field inserted after the frontmatter's `name:` line.
+ */
+function hideFromSlashMenu(content, target) {
+    if (target !== 'claude' || !content.startsWith('---\n') || content.includes('user-invocable:'))
+        return content;
+    return content.replace(/^(---\nname:[^\n]*\n)/, '$1user-invocable: false\n');
+}
+/**
+ * Generates the `/opsx` commands, `openspec-*` skills, and `openspec/` project
+ * structure for one harness under `projectDir`.
+ */
+export async function initProject(opts) {
+    const { target, projectDir } = opts;
+    const adapter = CommandAdapterRegistry.get(target);
+    if (!adapter) {
+        throw new Error(`No command adapter registered for target '${target}'. Supported targets: claude, opencode.`);
+    }
+    const written = [];
+    const notes = [];
+    // --- openspec/ project structure -----------------------------------------
+    const openspecDir = path.join(projectDir, 'openspec');
+    for (const dir of [
+        openspecDir,
+        path.join(openspecDir, 'specs'),
+        path.join(openspecDir, 'changes'),
+        path.join(openspecDir, 'changes', 'archive'),
+    ]) {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    // config.yaml is user-owned once it exists: a project's `context:` and `rules:`
+    // live there, so a re-run (bootstrap, update, --fix) must never rewrite it.
+    const configPath = path.join(openspecDir, 'config.yaml');
+    if (await pathExists(configPath)) {
+        notes.push(`openspec/config.yaml already exists; kept as is (context/rules preserved): ${configPath}`);
+    }
+    else {
+        await writeFileEnsuringDir(configPath, serializeConfig('spec-driven'));
+        written.push(configPath);
+    }
+    // --- skills ---------------------------------------------------------------
+    // The command-reference form differs per target: Claude Code registers the
+    // canonical `/opsx:<id>` (no rewrite); OpenCode registers `/opsx-<id>`, so
+    // skill bodies are rewritten to match. This mirrors upstream
+    // getTransformerForTool for these two adapter-backed, slash-prefixed tools.
+    const invocation = getInvocationForAdapter(adapter);
+    const skillTransformer = needsInvocationRewrite(invocation)
+        ? (text) => transformCommandInvocations(text, invocation)
+        : undefined;
+    const skillsRoot = path.join(projectDir, TOOL_SKILLS_DIR[target], 'skills');
+    for (const { template, dirName } of getSkillTemplates(CORE_WORKFLOWS)) {
+        const skillFile = path.join(skillsRoot, dirName, 'SKILL.md');
+        const content = hideFromSlashMenu(generateSkillContent(template, OPENSPEC_VENDOR_VERSION, skillTransformer), target);
+        await writeFileEnsuringDir(skillFile, content);
+        written.push(skillFile);
+    }
+    // --- commands -------------------------------------------------------------
+    // generateCommands applies the same invocation rewrite to command bodies and
+    // asks the adapter for the tool-specific path + frontmatter.
+    const commandContents = getCommandContents(CORE_WORKFLOWS);
+    for (const cmd of generateCommands(commandContents, adapter)) {
+        const commandFile = path.isAbsolute(cmd.path)
+            ? cmd.path
+            : path.join(projectDir, cmd.path);
+        await writeFileEnsuringDir(commandFile, cmd.fileContent);
+        written.push(commandFile);
+    }
+    return { written, notes };
+}

package/node_modules/@freeharness/sdd/dist/src/root-resolver.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Walks up from `startDir` looking for an `openspec/` directory.
+ *
+ * @param startDir - Directory to start searching from.
+ * @returns The absolute path to the nearest `openspec/` directory, or null if
+ *          none is found before reaching the filesystem root.
+ */
+export declare function findOpenspecDir(startDir: string): string | null;

package/node_modules/@freeharness/sdd/dist/src/root-resolver.js

@@ -0,0 +1,32 @@
+// Store-free project-root resolution. Unlike the upstream fork's root resolver,
+// this has no dependency on the ~/.openspec multi-repo store or worksets: it just
+// walks up from a starting directory looking for an `openspec/` directory.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Walks up from `startDir` looking for an `openspec/` directory.
+ *
+ * @param startDir - Directory to start searching from.
+ * @returns The absolute path to the nearest `openspec/` directory, or null if
+ *          none is found before reaching the filesystem root.
+ */
+export function findOpenspecDir(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, 'openspec');
+        try {
+            if (fs.statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // Not present at this level — keep walking up.
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            // Reached the filesystem root without a match.
+            return null;
+        }
+        current = parent;
+    }
+}

package/node_modules/@freeharness/sdd/dist/src/shim/archive.d.ts

@@ -0,0 +1,81 @@
+import type { ValidationIssue } from '../../vendor/openspec/validation/types.js';
+import { type UnresolvedDeltaHeader } from '../../vendor/openspec/validation/delta-resolution.js';
+import { type ChangeMetadata } from '../../vendor/openspec/engine/change-metadata.js';
+import { type FollowUpItem } from './follow-up.js';
+/** One `Supersedes:` link resolved against openspec/changes/archive/. */
+export interface SupersessionLink {
+    /** The superseded (archived) change id. */
+    change: string;
+    /** Absolute path of the archived record. */
+    path: string;
+}
+/**
+ * Resolves the ids a change supersedes: the deduplicated union of design.md's
+ * `Supersedes:` lines and the metadata `supersedes` list, design.md first.
+ */
+export declare function readSupersedes(designText: string, metadata: ChangeMetadata | null): string[];
+/**
+ * Resolves the change's `Supersedes:` lines and enforces the supersession
+ * rules: every id names an archived change, and no MODIFIED requirement of this
+ * change repeats a superseded requirement's text unchanged.
+ */
+export declare function checkSupersession(changeName: string, changeDir: string, changesDir: string, metadata: ChangeMetadata | null): Promise<SupersessionLink[]>;
+/**
+ * Lines that describe what archive would refuse or what is still open. The
+ * unresolved headers are listed here as well so one refusal names everything.
+ */
+export declare function listArchiveBlockers(changeDir: string, issues: ValidationIssue[], unresolved?: UnresolvedDeltaHeader[]): string[];
+/** One unchecked task resolved outside this change. */
+export interface ArchivedDisposition {
+    kind: string;
+    task: string;
+    target: string;
+}
+export interface ArchiveChangeOptions {
+    /** Project root (the parent of the openspec/ directory). */
+    projectRoot: string;
+    /**
+     * Skips the blockers gate (unchecked tasks, deltas archive would refuse),
+     * as upstream `--yes` skips its confirmation prompt. Without it, a change
+     * with blockers is listed and refused with nothing written.
+     */
+    yes?: boolean;
+    /**
+     * Archives despite unresolved MODIFIED / REMOVED / RENAMED headers: the fold
+     * skips those deltas (each printed as a warning) and the rest is applied.
+     * Without it, any unresolved header refuses the archive with nothing written.
+     */
+    force?: boolean;
+}
+export interface ArchiveChangeResult {
+    /** Capability ids whose main spec was updated by the fold. */
+    applied: string[];
+    /** Absolute path the change directory was moved to. */
+    archivedTo: string;
+    /** Archived changes this change supersedes (from design.md `Supersedes:`). */
+    supersedes: SupersessionLink[];
+    /** Delta headers skipped by the fold under `--force` (empty otherwise). */
+    skipped: UnresolvedDeltaHeader[];
+    /** Unchecked tasks resolved outside this change, grouped for display by kind. */
+    dispositions: ArchivedDisposition[];
+    /** The archived change's unclaimed follow-ups, printed as a notice (never a blocker). */
+    followUps: FollowUpItem[];
+}
+/**
+ * Archive a change: validate it, fold its delta specs into openspec/specs/, then
+ * move openspec/changes/<name>/ to openspec/changes/archive/<name>/.
+ *
+ * Throws (with an actionable message) rather than partially archiving when the
+ * change is invalid, a fold fails, or the archive destination is already taken.
+ */
+export declare function archiveChange(changeName: string | undefined, { projectRoot, yes, force }: ArchiveChangeOptions): Promise<ArchiveChangeResult>;
+export interface ArchiveOptions {
+    json?: boolean;
+    yes?: boolean;
+    force?: boolean;
+}
+/**
+ * CLI wrapper for `openspec archive <id>`. Returns the process exit code and
+ * emits either the single-document `--json` result or human-readable lines.
+ */
+export declare function archiveHandler(projectRoot: string, changeName: string | undefined, options: ArchiveOptions): Promise<number>;