@gordon.gan/specflow 1.1.0 → 1.2.0-beta

package/dist/core/worksets.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export interface WorksetMember {
+    readonly name: string;
+    readonly path: string;
+}
+export interface Workset {
+    readonly name: string;
+    readonly members: readonly WorksetMember[];
+    readonly tool?: string;
+}
+declare const WorksetsStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    worksets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        members: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+            name: string;
+        }, {
+            path: string;
+            name: string;
+        }>, "many">;
+        tool: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }, {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    worksets: {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }[];
+    version: 1;
+}, {
+    worksets: {
+        name: string;
+        members: {
+            path: string;
+            name: string;
+        }[];
+        tool?: string | undefined;
+    }[];
+    version: 1;
+}>;
+export type WorksetsState = z.infer<typeof WorksetsStateSchema>;
+export declare function validateWorksetName(name: string): void;
+export declare function validateWorksetMembers(members: readonly WorksetMember[]): void;
+export declare function readWorksetsState(statePath: string): Promise<WorksetsState>;
+export declare function updateWorksetsState(statePath: string, updater: (state: WorksetsState) => WorksetsState): Promise<WorksetsState>;
+export declare function withWorkset(state: WorksetsState, workset: Workset): WorksetsState;
+export declare function getWorksetCodeWorkspacePath(dataDir: string, name: string): string;
+export declare function defaultWorksetsStatePath(dataDir?: string): string;
+export declare function removeWorksetByName(statePath: string, name: string, dataDir: string): Promise<boolean>;
+export {};

package/dist/core/worksets.js

@@ -0,0 +1,134 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { acquireFileLock, releaseFileLock, writeFileAtomically, makeLockErrorFactory } from './file-state.js';
+import { getWorksetsStatePath } from './global-config.js';
+import { StoreError } from './store/foundation.js';
+const KEBAB_CASE_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const WorksetMemberSchema = z.object({ name: z.string(), path: z.string() }).strict();
+const WorksetSchema = z
+    .object({
+    name: z.string(),
+    members: z.array(WorksetMemberSchema).min(1),
+    tool: z.string().optional(),
+})
+    .strict();
+const WorksetsStateSchema = z.object({
+    version: z.literal(1),
+    worksets: z.array(WorksetSchema),
+});
+function lockPathFor(statePath) {
+    return `${statePath}.lock`;
+}
+function makeWorksetLockError() {
+    return makeLockErrorFactory({
+        createSubject: 'the workset lock file',
+        busyMessage: 'Workset state is busy.',
+        code: 'workset_busy',
+        target: 'worksets.state',
+    });
+}
+export function validateWorksetName(name) {
+    if (!KEBAB_CASE_NAME.test(name)) {
+        throw new StoreError(`Invalid workset name '${name}'.`, {
+            severity: 'error',
+            code: 'invalid_workset_name',
+            message: 'Workset names must be kebab-case.',
+            target: 'workset.name',
+        });
+    }
+}
+export function validateWorksetMembers(members) {
+    if (members.length === 0) {
+        throw new StoreError('Workset must contain at least one member.', {
+            severity: 'error',
+            code: 'invalid_workset_members',
+            message: 'Worksets require at least one member.',
+            target: 'workset.members',
+        });
+    }
+    const labels = new Set();
+    for (const member of members) {
+        if (!path.isAbsolute(member.path)) {
+            throw new StoreError(`Member path must be absolute: ${member.path}`, {
+                severity: 'error',
+                code: 'invalid_workset_path',
+                message: 'Workset member paths must be absolute.',
+                target: `workset.members.${member.name}`,
+            });
+        }
+        if (labels.has(member.name)) {
+            throw new StoreError(`Duplicate workset member label '${member.name}'.`, {
+                severity: 'error',
+                code: 'duplicate_workset_member',
+                message: 'Workset member labels must be unique.',
+                target: `workset.members.${member.name}`,
+            });
+        }
+        labels.add(member.name);
+    }
+}
+export async function readWorksetsState(statePath) {
+    try {
+        const content = await fs.readFile(statePath, 'utf-8');
+        const parsed = yaml.load(content);
+        return WorksetsStateSchema.parse(parsed);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: 1, worksets: [] };
+        }
+        throw error;
+    }
+}
+async function writeWorksetsState(statePath, state) {
+    const content = yaml.dump(state, { lineWidth: -1, noRefs: true });
+    await writeFileAtomically(statePath, content);
+}
+export async function updateWorksetsState(statePath, updater) {
+    const lock = await acquireFileLock({
+        lockPath: lockPathFor(statePath),
+        errorFor: makeWorksetLockError(),
+    });
+    try {
+        const current = await readWorksetsState(statePath);
+        const next = WorksetsStateSchema.parse(updater(current));
+        await writeWorksetsState(statePath, next);
+        return next;
+    }
+    finally {
+        await releaseFileLock(lock, lockPathFor(statePath));
+    }
+}
+export function withWorkset(state, workset) {
+    validateWorksetName(workset.name);
+    validateWorksetMembers(workset.members);
+    const without = state.worksets.filter((entry) => entry.name !== workset.name);
+    return { version: 1, worksets: [...without, workset].sort((a, b) => a.name.localeCompare(b.name)) };
+}
+export function getWorksetCodeWorkspacePath(dataDir, name) {
+    return path.join(dataDir, 'worksets', `${name}.code-workspace`);
+}
+export function defaultWorksetsStatePath(dataDir) {
+    return getWorksetsStatePath(dataDir);
+}
+export async function removeWorksetByName(statePath, name, dataDir) {
+    let removed = false;
+    await updateWorksetsState(statePath, (state) => {
+        const exists = state.worksets.some((entry) => entry.name === name);
+        if (!exists) {
+            return state;
+        }
+        removed = true;
+        return {
+            version: 1,
+            worksets: state.worksets.filter((entry) => entry.name !== name),
+        };
+    });
+    if (removed) {
+        const workspacePath = getWorksetCodeWorkspacePath(dataDir, name);
+        await fs.rm(workspacePath, { force: true }).catch(() => undefined);
+    }
+    return removed;
+}

package/dist/integrations/shared/skill-renderer.d.ts

@@ -1,4 +1,10 @@
 import type { IdeTarget } from './types.js';
+import type { ReferencedStoresSection } from '../../core/artifact-graph/instruction-loader.js';
+export interface ReferenceGuidanceInput {
+    readonly referencedStores?: ReferencedStoresSection;
+}
+/** Renders identical reference guidance for every IDE target. */
+export declare function collectReferenceGuidance(input: ReferenceGuidanceInput): Record<IdeTarget, string>;
 export declare function renderIdeContent(content: string, ide: IdeTarget): string;
 /** @deprecated Use renderIdeContent */
 export declare const renderSkillContent: typeof renderIdeContent;

package/dist/integrations/shared/skill-renderer.js

@@ -1,4 +1,26 @@
 import { COMMAND_CATALOG } from './command-catalog.js';
+function formatReferenceBlock(section) {
+    if (!section || section.rendered.trim().length === 0) {
+        return '';
+    }
+    const lines = [
+        '## Referenced store index (read-only)',
+        section.rendered,
+    ];
+    if (section.truncated) {
+        lines.push('Index truncated. Use `specflow show <spec-id> --type spec --store <store-id>` to fetch full specs.');
+    }
+    return lines.join('\n');
+}
+/** Renders identical reference guidance for every IDE target. */
+export function collectReferenceGuidance(input) {
+    const block = formatReferenceBlock(input.referencedStores);
+    return {
+        claude: block,
+        cursor: block,
+        codex: block,
+    };
+}
 function runtimePrefix(ide) {
     if (ide === 'claude') {
         return '.claude/specflow/';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.1.0",
+  "version": "1.2.0-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [