freeharness 0.4.1

package/node_modules/@freeharness/sdd/dist/src/shim/new-change.js

@@ -0,0 +1,150 @@
+// `openspec new change <id> [--schema <name>] [--json]` — store-free.
+//
+// Reconstructed from src/commands/workflow/new-change.ts + src/utils/change-utils.ts,
+// minus store/root-selection and the project-config schema fallback. Schema
+// resolution is: explicit --schema -> 'spec-driven'. Creating a change also
+// scaffolds the surrounding root (specs/, changes/archive/, config.yaml) exactly
+// like upstream, so a fresh openspec/ is left healthy. JSON shape matches
+// upstream: { change: { id, path, metadataPath, schema } }.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { writeChangeMetadata, METADATA_FILENAME, countTasksFromContent, } from '../../vendor/openspec/engine/index.js';
+import { getAvailableChanges, planningHomeStub, printableId, printJson, validateSchemaExists } from './shared.js';
+const DEFAULT_WIP_CAP = 1;
+const WIP_CAP_FILE = '.freeharness/sdd.json';
+/**
+ * Reads `wip_cap` from `.freeharness/sdd.json` at the project root: absent file
+ * means the default silently; an unreadable or unparseable file, or a `wip_cap`
+ * that is not a positive integer, means the default plus one INFO line naming
+ * the file. Read synchronously with a try/catch, never `require` or `import`.
+ */
+function readWipCap(projectRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectRoot, WIP_CAP_FILE), 'utf-8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { cap: DEFAULT_WIP_CAP, info: null };
+        return { cap: DEFAULT_WIP_CAP, info: `INFO ${WIP_CAP_FILE}: wip_cap invalid, using ${DEFAULT_WIP_CAP}` };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const cap = parsed.wip_cap;
+        if (typeof cap === 'number' && Number.isInteger(cap) && cap > 0) {
+            return { cap, info: null };
+        }
+    }
+    catch {
+        // falls through to the malformed-default below
+    }
+    return { cap: DEFAULT_WIP_CAP, info: `INFO ${WIP_CAP_FILE}: wip_cap invalid, using ${DEFAULT_WIP_CAP}` };
+}
+/**
+ * In-flight change ids (excluding archive) whose tasks.md has an open task
+ * (unchecked, no disposition) or has no tasks.md at all.
+ */
+function inFlightChangeIds(projectRoot) {
+    const changesDir = path.join(projectRoot, 'openspec', 'changes');
+    const ids = [];
+    for (const id of getAvailableChanges(projectRoot)) {
+        const tasksPath = path.join(changesDir, id, 'tasks.md');
+        let hasOpenTasks = true;
+        if (fs.existsSync(tasksPath)) {
+            hasOpenTasks = countTasksFromContent(fs.readFileSync(tasksPath, 'utf-8')).open > 0;
+        }
+        if (hasOpenTasks)
+            ids.push(id);
+    }
+    return ids;
+}
+const DEFAULT_SCHEMA = 'spec-driven';
+const KEBAB_ID_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+function validateChangeName(name) {
+    if (!name)
+        throw new Error('Change name cannot be empty');
+    if (name.length > 200)
+        throw new Error('Change name is too long (200 characters max)');
+    if (!KEBAB_ID_REGEX.test(name)) {
+        if (/[A-Z]/.test(name))
+            throw new Error('Change name must be lowercase (use kebab-case)');
+        if (/\s/.test(name))
+            throw new Error('Change name cannot contain spaces (use hyphens instead)');
+        if (/_/.test(name))
+            throw new Error('Change name cannot contain underscores (use hyphens instead)');
+        if (name.startsWith('-'))
+            throw new Error('Change name cannot start with a hyphen');
+        if (name.endsWith('-'))
+            throw new Error('Change name cannot end with a hyphen');
+        if (/--/.test(name))
+            throw new Error('Change name cannot contain consecutive hyphens');
+        throw new Error('Change name must follow kebab-case convention (e.g., add-auth, refactor-db)');
+    }
+}
+function formatLocalDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+export function newChangeHandler(projectRoot, name, options) {
+    if (!name)
+        throw new Error('Missing required argument <name>');
+    validateChangeName(name);
+    const schemaName = options.schema ?? DEFAULT_SCHEMA;
+    validateSchemaExists(schemaName, projectRoot);
+    const openspecDir = path.join(projectRoot, 'openspec');
+    const changeDir = path.join(openspecDir, 'changes', name);
+    if (fs.existsSync(changeDir)) {
+        throw new Error(`Change '${name}' already exists at ${changeDir}`);
+    }
+    // WIP advisory: read before the new change directory exists, so it is never
+    // counted among the in-flight changes it might be advised against joining.
+    // A count of zero prints nothing, not even the malformed-config INFO line: the advisory has
+    // nothing to say.
+    const inFlight = inFlightChangeIds(projectRoot);
+    const wipCap = inFlight.length > 0 ? readWipCap(projectRoot) : { cap: DEFAULT_WIP_CAP, info: null };
+    fs.mkdirSync(changeDir, { recursive: true });
+    fs.mkdirSync(path.join(openspecDir, 'specs'), { recursive: true });
+    fs.mkdirSync(path.join(openspecDir, 'changes', 'archive'), { recursive: true });
+    const configPath = path.join(openspecDir, 'config.yaml');
+    const configYmlPath = path.join(openspecDir, 'config.yml');
+    if (!fs.existsSync(configPath) && !fs.existsSync(configYmlPath)) {
+        fs.writeFileSync(configPath, `schema: ${DEFAULT_SCHEMA}\n`, 'utf-8');
+    }
+    writeChangeMetadata(changeDir, { schema: schemaName, created: formatLocalDate() }, projectRoot);
+    if (options.description) {
+        fs.writeFileSync(path.join(changeDir, 'README.md'), `# ${name}\n\n${options.description}\n`, 'utf-8');
+    }
+    const wipAdvisory = inFlight.length >= wipCap.cap
+        ? { count: inFlight.length, cap: wipCap.cap, changes: inFlight.map(printableId) }
+        : null;
+    const notices = wipCap.info ? [wipCap.info] : [];
+    const payload = {
+        change: {
+            id: name,
+            path: changeDir,
+            metadataPath: path.join(changeDir, METADATA_FILENAME),
+            schema: schemaName,
+        },
+        planningHome: planningHomeStub(projectRoot),
+        changeRoot: changeDir,
+        wip_advisory: wipAdvisory,
+        notices,
+    };
+    if (options.json) {
+        printJson(payload);
+        return 0;
+    }
+    console.log(`Created change '${name}' at ${changeDir}/`);
+    console.log(`Schema: ${schemaName}`);
+    console.log(`Next: openspec status --change ${name}`);
+    for (const notice of notices)
+        console.log(notice);
+    if (wipAdvisory) {
+        console.log(`WIP advisory: ${wipAdvisory.count} change(s) in flight (cap ${wipAdvisory.cap}): ${wipAdvisory.changes.join(', ')}; ` +
+            'finish or archive before opening another');
+    }
+    return 0;
+}

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

@@ -0,0 +1,4 @@
+export interface SchemasOptions {
+    json?: boolean;
+}
+export declare function schemasHandler(projectRoot: string, options: SchemasOptions): number;

package/node_modules/@freeharness/sdd/dist/src/shim/schemas.js

@@ -0,0 +1,23 @@
+// `openspec schemas --json` over the vendored engine.
+//
+// Reconstructed from src/commands/workflow/schemas.ts, minus store/root-selection
+// and chalk. JSON output is the SchemaInfo[] array upstream emits verbatim.
+import { listSchemasWithInfo } from '../../vendor/openspec/engine/index.js';
+import { printJson } from './shared.js';
+export function schemasHandler(projectRoot, options) {
+    const schemas = listSchemasWithInfo(projectRoot);
+    if (options.json) {
+        printJson(schemas);
+        return 0;
+    }
+    console.log('Available schemas:');
+    console.log();
+    for (const schema of schemas) {
+        const sourceLabel = schema.source === 'project' ? ' (project)' : schema.source === 'user' ? ' (user override)' : '';
+        console.log(`  ${schema.name}${sourceLabel}`);
+        console.log(`    ${schema.description}`);
+        console.log(`    Artifacts: ${schema.artifacts.join(' -> ')}`);
+        console.log();
+    }
+    return 0;
+}

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

@@ -0,0 +1,56 @@
+/** Emits a value as pretty JSON on stdout (the single-document `--json` contract). */
+export declare function printJson(payload: unknown): void;
+/**
+ * A task's numbering label for a message (the leading `N.N` of its
+ * description), falling back to its line number when the description carries
+ * none. Shared by every reader that names a task in an issue or a blocker.
+ */
+export declare function taskLabel(task: {
+    description: string;
+    line: number;
+}): string;
+/** The changes directory for a project root. */
+export declare function changesDirFor(projectRoot: string): string;
+/**
+ * Store-free stand-in for upstream's `planningHome` (#1703, OpenSpec 1.12).
+ * Upstream resolves the planning home against a registered store; this slice
+ * has no store, so the planning home is always the local repository root. The
+ * /opsx skills compose main-spec paths from `planningHome.root` and archive
+ * paths from `planningHome.changesDir`, so both are carried.
+ */
+export interface PlanningHomeStub {
+    kind: 'local';
+    root: string;
+    changesDir: string;
+    defaultSchema: string;
+}
+/** Builds the planningHome stub for a resolved project root. */
+export declare function planningHomeStub(projectRoot: string): PlanningHomeStub;
+/**
+ * Lists active change directory names under openspec/changes/, excluding the
+ * archive directory and hidden entries.
+ */
+export declare function getAvailableChanges(projectRoot: string): string[];
+/**
+ * A change id as a command prints it: a directory name is data, so a control character in it
+ * can never break the printed line in two or reach the agent reading the output as a line of
+ * its own.
+ */
+export declare function printableId(id: string): string;
+/**
+ * Resolves a `depends_on` / `supersedes` change id against the project: `"in-flight"`
+ * when it names a directory under `openspec/changes/`, `"archived"` when it names one
+ * under `openspec/changes/archive/`, else `null`. An id with a path separator, a `..`
+ * segment or the reserved `archive` name never resolves, so a list entry cannot escape
+ * either tree or alias the archive directory itself. The entry is stat'd without following
+ * links, so a symlink planted in the changes tree is not a change and a writer such as
+ * `follow-up add` never lands at its target.
+ */
+export declare function resolveChangeId(projectRoot: string, id: string): 'in-flight' | 'archived' | null;
+/**
+ * Validates that a change exists; throws with the available-changes list when
+ * it does not. Mirrors upstream `validateChangeExists`.
+ */
+export declare function validateChangeExists(changeName: string | undefined, projectRoot: string): string;
+/** Validates that a schema resolves; throws with the available list otherwise. */
+export declare function validateSchemaExists(schemaName: string, projectRoot?: string): string;

package/node_modules/@freeharness/sdd/dist/src/shim/shared.js

@@ -0,0 +1,140 @@
+// Shared helpers for the store-free `openspec` CLI shim.
+//
+// These reimplement, over the vendored engine, the small validation/discovery
+// helpers the upstream `src/commands/workflow/shared.ts` provided — minus the
+// store/root-selection coupling (root resolution is the shim's job, see
+// src/root-resolver.ts).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getSchemaDir, listSchemas } from '../../vendor/openspec/engine/index.js';
+/** Emits a value as pretty JSON on stdout (the single-document `--json` contract). */
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+const TASK_ID = /^(\d+(?:\.\d+)+(?:[A-Za-z]+)?)(?=\s|$)/;
+/**
+ * A task's numbering label for a message (the leading `N.N` of its
+ * description), falling back to its line number when the description carries
+ * none. Shared by every reader that names a task in an issue or a blocker.
+ */
+export function taskLabel(task) {
+    return task.description.match(TASK_ID)?.[1] ?? `line ${task.line}`;
+}
+/** The changes directory for a project root. */
+export function changesDirFor(projectRoot) {
+    return path.join(projectRoot, 'openspec', 'changes');
+}
+/** Builds the planningHome stub for a resolved project root. */
+export function planningHomeStub(projectRoot) {
+    return {
+        kind: 'local',
+        root: projectRoot,
+        changesDir: changesDirFor(projectRoot),
+        defaultSchema: 'spec-driven',
+    };
+}
+/**
+ * Lists active change directory names under openspec/changes/, excluding the
+ * archive directory and hidden entries.
+ */
+export function getAvailableChanges(projectRoot) {
+    const dir = changesDirFor(projectRoot);
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name !== 'archive' && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/**
+ * A change id as a command prints it: a directory name is data, so a control character in it
+ * can never break the printed line in two or reach the agent reading the output as a line of
+ * its own.
+ */
+export function printableId(id) {
+    return id.replace(/[\x00-\x1f\x7f]/g, '');
+}
+/**
+ * Resolves a `depends_on` / `supersedes` change id against the project: `"in-flight"`
+ * when it names a directory under `openspec/changes/`, `"archived"` when it names one
+ * under `openspec/changes/archive/`, else `null`. An id with a path separator, a `..`
+ * segment or the reserved `archive` name never resolves, so a list entry cannot escape
+ * either tree or alias the archive directory itself. The entry is stat'd without following
+ * links, so a symlink planted in the changes tree is not a change and a writer such as
+ * `follow-up add` never lands at its target.
+ */
+export function resolveChangeId(projectRoot, id) {
+    if (!id || id === '.' || id === '..' || id === 'archive' || id.includes('/') || id.includes('\\') || id.includes('\0')) {
+        return null;
+    }
+    const changesDir = changesDirFor(projectRoot);
+    if (isRealDirectory(path.join(changesDir, id)))
+        return 'in-flight';
+    if (isRealDirectory(path.join(changesDir, 'archive', id)))
+        return 'archived';
+    return null;
+}
+/** True for a directory that is not a symlink; false for anything else, including an absent path. */
+function isRealDirectory(entry) {
+    try {
+        return fs.lstatSync(entry).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Rejects change names that would escape the changes directory. */
+function validateChangeLookupName(changeName) {
+    if (changeName === '.' || changeName === '..')
+        return 'Change name cannot be a relative path segment';
+    if (changeName.includes('/') || changeName.includes('\\'))
+        return 'Change name cannot contain path separators';
+    if (changeName.includes('\0'))
+        return 'Change name cannot contain null characters';
+    if (changeName.startsWith('.'))
+        return 'Change name cannot start with a dot';
+    if (changeName === 'archive')
+        return "'archive' is reserved for archived changes";
+    return undefined;
+}
+/**
+ * Validates that a change exists; throws with the available-changes list when
+ * it does not. Mirrors upstream `validateChangeExists`.
+ */
+export function validateChangeExists(changeName, projectRoot) {
+    if (!changeName) {
+        const available = getAvailableChanges(projectRoot);
+        if (available.length === 0) {
+            throw new Error('No changes found. Create one with: openspec new change <name>');
+        }
+        throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    const lookupError = validateChangeLookupName(changeName);
+    if (lookupError) {
+        throw new Error(`Invalid change name '${changeName}': ${lookupError}`);
+    }
+    const changePath = path.join(changesDirFor(projectRoot), changeName);
+    const exists = fs.existsSync(changePath) && fs.statSync(changePath).isDirectory();
+    if (!exists) {
+        const available = getAvailableChanges(projectRoot);
+        if (available.length === 0) {
+            throw new Error(`Change '${changeName}' not found. No changes exist. Create one with: openspec new change <name>`);
+        }
+        throw new Error(`Change '${changeName}' not found. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    return changeName;
+}
+/** Validates that a schema resolves; throws with the available list otherwise. */
+export function validateSchemaExists(schemaName, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
+    if (!schemaDir) {
+        const available = listSchemas(projectRoot);
+        throw new Error(`Schema '${schemaName}' not found. Available schemas:\n  ${available.join('\n  ')}`);
+    }
+    return schemaName;
+}

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

@@ -0,0 +1,8 @@
+import { type ChangeStatus } from '../../vendor/openspec/engine/index.js';
+export interface StatusOptions {
+    change?: string;
+    schema?: string;
+    json?: boolean;
+}
+export declare function statusHandler(projectRoot: string, options: StatusOptions): Promise<number>;
+export declare function printStatusText(status: ChangeStatus): void;

package/node_modules/@freeharness/sdd/dist/src/shim/status.js

@@ -0,0 +1,85 @@
+// `openspec status --change <id> [--json]` over the vendored engine.
+//
+// Reconstructed from src/commands/workflow/status.ts, minus store/root-selection
+// and the ora spinner. The JSON shape preserves the fields the /opsx skills read
+// (artifacts[].status, artifacts[].requires, applyRequires, isPlanningComplete /
+// isComplete). The store-only `root` field is omitted; `planningHome` is the
+// store-free stub from shared.ts (V4-P4, #1703).
+import { loadChangeContext, formatChangeStatus, getTaskProgressForChange, } from '../../vendor/openspec/engine/index.js';
+import { changesDirFor, getAvailableChanges, planningHomeStub, printJson, validateChangeExists, validateSchemaExists, } from './shared.js';
+export async function statusHandler(projectRoot, options) {
+    if (!options.change) {
+        const available = getAvailableChanges(projectRoot);
+        if (available.length === 0) {
+            if (options.json) {
+                printJson({ changes: [], message: 'No active changes.' });
+                return 0;
+            }
+            console.log('No active changes. Create one with: openspec new change <name>');
+            return 0;
+        }
+        throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    const changeName = validateChangeExists(options.change, projectRoot);
+    if (options.schema) {
+        validateSchemaExists(options.schema, projectRoot);
+    }
+    const context = loadChangeContext(projectRoot, changeName, options.schema);
+    const status = formatChangeStatus(context);
+    // Task-level counts (done/open/dispositioned) are orthogonal to the planning
+    // artifacts' status above: a dispositioned task is resolved without being
+    // checked, so the tasks artifact is complete for a reader's purposes exactly
+    // when `open` reaches zero.
+    const taskProgress = await getTaskProgressForChange(changesDirFor(projectRoot), changeName, projectRoot);
+    if (options.json) {
+        printJson({
+            ...status,
+            done: taskProgress.done,
+            open: taskProgress.open,
+            dispositioned: taskProgress.dispositioned,
+            planningHome: planningHomeStub(projectRoot),
+        });
+        return 0;
+    }
+    printStatusText(status);
+    return 0;
+}
+function indicator(status) {
+    switch (status) {
+        case 'done':
+            return '[x]';
+        case 'skipped':
+            return '[~]';
+        case 'ready':
+            return '[ ]';
+        case 'blocked':
+            return '[-]';
+    }
+}
+export function printStatusText(status) {
+    const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
+    const skippedCount = status.artifacts.filter((a) => a.status === 'skipped').length;
+    const total = status.artifacts.length - skippedCount;
+    console.log(`Change: ${status.changeName}`);
+    console.log(`Schema: ${status.schemaName}`);
+    if (status.changeRoot) {
+        console.log(`Change root: ${status.changeRoot}`);
+    }
+    const skippedSuffix = skippedCount > 0 ? ` (${skippedCount} skipped)` : '';
+    console.log(`Progress: ${doneCount}/${total} artifacts complete${skippedSuffix}`);
+    console.log();
+    for (const artifact of status.artifacts) {
+        let line = `${indicator(artifact.status)} ${artifact.id}`;
+        if (artifact.status === 'skipped') {
+            line += ' (skipped: change declares skip_specs)';
+        }
+        if (artifact.status === 'blocked' && artifact.missingDeps && artifact.missingDeps.length > 0) {
+            line += ` (blocked by: ${artifact.missingDeps.join(', ')})`;
+        }
+        console.log(line);
+    }
+    if (status.isPlanningComplete) {
+        console.log();
+        console.log('All planning artifacts complete!');
+    }
+}

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

@@ -0,0 +1,6 @@
+export interface ValidateOptions {
+    specs?: boolean;
+    strict?: boolean;
+    json?: boolean;
+}
+export declare function validateHandler(projectRoot: string, item: string | undefined, options: ValidateOptions): Promise<number>;