@sudocode-ai/integration-openspec 0.1.14

package/dist/id-generator.d.ts

@@ -0,0 +1,114 @@
+/**
+ * OpenSpec ID Generator
+ *
+ * Generates deterministic, path-based IDs for OpenSpec entities.
+ * IDs are stable across syncs - the same input always produces the same output.
+ *
+ * ID Format:
+ * - Specs: os-xxxx (e.g., os-a1b2)
+ * - Changes: osc-xxxx (e.g., osc-c3d4)
+ */
+/** Default prefix for OpenSpec spec IDs */
+export declare const DEFAULT_SPEC_PREFIX = "os";
+/** Default prefix for OpenSpec change IDs */
+export declare const DEFAULT_CHANGE_PREFIX = "osc";
+/**
+ * Generate a deterministic spec ID from a capability name.
+ *
+ * The ID is generated by hashing "openspec-spec-{capability}" and
+ * taking the first 4 hex characters.
+ *
+ * @param capability - The capability name (e.g., "cli-init")
+ * @param prefix - ID prefix (default: "os")
+ * @returns Deterministic spec ID (e.g., "os-a1b2")
+ *
+ * @example
+ * generateSpecId("cli-init") // Returns same ID every time
+ * generateSpecId("cli-init", "os") // Same as above, explicit prefix
+ * generateSpecId("cli-init", "spec") // "spec-a1b2"
+ */
+export declare function generateSpecId(capability: string, prefix?: string): string;
+/**
+ * Generate a deterministic change ID from a change name.
+ *
+ * The ID is generated by hashing "openspec-change-{changeName}" and
+ * taking the first 4 hex characters.
+ *
+ * @param changeName - The change name (e.g., "add-feature")
+ * @param prefix - ID prefix (default: "osc")
+ * @returns Deterministic change ID (e.g., "osc-c3d4")
+ *
+ * @example
+ * generateChangeId("add-feature") // Returns same ID every time
+ * generateChangeId("add-feature", "osc") // Same as above, explicit prefix
+ * generateChangeId("add-feature", "ch") // "ch-c3d4"
+ */
+export declare function generateChangeId(changeName: string, prefix?: string): string;
+/**
+ * Parsed result from an OpenSpec ID
+ */
+export interface ParsedOpenSpecId {
+    /** Entity type: 'spec' or 'change' */
+    type: "spec" | "change";
+    /** The original name used to generate this ID (if recoverable) */
+    name: string;
+    /** The hash portion of the ID */
+    hash: string;
+    /** The prefix portion of the ID */
+    prefix: string;
+}
+/**
+ * Parse an OpenSpec ID to extract its components.
+ *
+ * Note: This only extracts structural information from the ID.
+ * The original name cannot be recovered from the hash alone -
+ * it must be provided or looked up separately.
+ *
+ * OpenSpec IDs require at least a 2-character prefix to distinguish
+ * them from sudocode IDs (which use single-character prefixes like s- and i-).
+ *
+ * @param id - The OpenSpec ID to parse (e.g., "os-a1b2" or "osc-c3d4")
+ * @returns Parsed ID components, or null if invalid format
+ *
+ * @example
+ * parseOpenSpecId("os-a1b2")
+ * // Returns: { type: "spec", name: "", hash: "a1b2", prefix: "os" }
+ *
+ * parseOpenSpecId("osc-c3d4")
+ * // Returns: { type: "change", name: "", hash: "c3d4", prefix: "osc" }
+ *
+ * parseOpenSpecId("invalid")
+ * // Returns: null
+ *
+ * parseOpenSpecId("s-abcd")
+ * // Returns: null (sudocode format, not OpenSpec)
+ */
+export declare function parseOpenSpecId(id: string): ParsedOpenSpecId | null;
+/**
+ * Verify that a given ID matches the expected ID for a name.
+ *
+ * Useful for validating that an ID was generated correctly.
+ *
+ * @param id - The ID to verify
+ * @param name - The name that should produce this ID
+ * @param type - Entity type ('spec' or 'change')
+ * @returns True if the ID matches what would be generated from the name
+ *
+ * @example
+ * verifyOpenSpecId("os-a1b2", "cli-init", "spec") // true or false
+ */
+export declare function verifyOpenSpecId(id: string, name: string, type: "spec" | "change"): boolean;
+/**
+ * Check if a string is a valid OpenSpec ID format.
+ *
+ * @param id - The string to check
+ * @returns True if the string matches OpenSpec ID format
+ *
+ * @example
+ * isOpenSpecId("os-a1b2")  // true
+ * isOpenSpecId("osc-c3d4") // true
+ * isOpenSpecId("invalid")  // false
+ * isOpenSpecId("s-abcd")   // false (sudocode format, not OpenSpec)
+ */
+export declare function isOpenSpecId(id: string): boolean;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../src/id-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,2CAA2C;AAC3C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAkB3C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAA4B,GACnC,MAAM,CAUR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAA8B,GACrC,MAAM,CAUR;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA2BnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,QAAQ,GACtB,OAAO,CAYT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/id-generator.js

@@ -0,0 +1,165 @@
+/**
+ * OpenSpec ID Generator
+ *
+ * Generates deterministic, path-based IDs for OpenSpec entities.
+ * IDs are stable across syncs - the same input always produces the same output.
+ *
+ * ID Format:
+ * - Specs: os-xxxx (e.g., os-a1b2)
+ * - Changes: osc-xxxx (e.g., osc-c3d4)
+ */
+import { createHash } from "crypto";
+/** Default prefix for OpenSpec spec IDs */
+export const DEFAULT_SPEC_PREFIX = "os";
+/** Default prefix for OpenSpec change IDs */
+export const DEFAULT_CHANGE_PREFIX = "osc";
+/** Default hash length (4 hex characters) */
+const DEFAULT_HASH_LENGTH = 4;
+/**
+ * Generate a deterministic hash from an input string.
+ * Uses SHA256 and takes the first N hex characters.
+ *
+ * @param input - The input string to hash
+ * @param length - Number of hex characters to return (default: 4)
+ * @returns Lowercase hex hash substring
+ */
+function generateHash(input, length = DEFAULT_HASH_LENGTH) {
+    const hash = createHash("sha256").update(input).digest("hex");
+    return hash.substring(0, length).toLowerCase();
+}
+/**
+ * Generate a deterministic spec ID from a capability name.
+ *
+ * The ID is generated by hashing "openspec-spec-{capability}" and
+ * taking the first 4 hex characters.
+ *
+ * @param capability - The capability name (e.g., "cli-init")
+ * @param prefix - ID prefix (default: "os")
+ * @returns Deterministic spec ID (e.g., "os-a1b2")
+ *
+ * @example
+ * generateSpecId("cli-init") // Returns same ID every time
+ * generateSpecId("cli-init", "os") // Same as above, explicit prefix
+ * generateSpecId("cli-init", "spec") // "spec-a1b2"
+ */
+export function generateSpecId(capability, prefix = DEFAULT_SPEC_PREFIX) {
+    if (!capability || capability.trim() === "") {
+        throw new Error("Capability name is required for spec ID generation");
+    }
+    const normalizedCapability = capability.trim().toLowerCase();
+    const hashInput = `openspec-spec-${normalizedCapability}`;
+    const hash = generateHash(hashInput);
+    return `${prefix}-${hash}`;
+}
+/**
+ * Generate a deterministic change ID from a change name.
+ *
+ * The ID is generated by hashing "openspec-change-{changeName}" and
+ * taking the first 4 hex characters.
+ *
+ * @param changeName - The change name (e.g., "add-feature")
+ * @param prefix - ID prefix (default: "osc")
+ * @returns Deterministic change ID (e.g., "osc-c3d4")
+ *
+ * @example
+ * generateChangeId("add-feature") // Returns same ID every time
+ * generateChangeId("add-feature", "osc") // Same as above, explicit prefix
+ * generateChangeId("add-feature", "ch") // "ch-c3d4"
+ */
+export function generateChangeId(changeName, prefix = DEFAULT_CHANGE_PREFIX) {
+    if (!changeName || changeName.trim() === "") {
+        throw new Error("Change name is required for change ID generation");
+    }
+    const normalizedChangeName = changeName.trim().toLowerCase();
+    const hashInput = `openspec-change-${normalizedChangeName}`;
+    const hash = generateHash(hashInput);
+    return `${prefix}-${hash}`;
+}
+/**
+ * Parse an OpenSpec ID to extract its components.
+ *
+ * Note: This only extracts structural information from the ID.
+ * The original name cannot be recovered from the hash alone -
+ * it must be provided or looked up separately.
+ *
+ * OpenSpec IDs require at least a 2-character prefix to distinguish
+ * them from sudocode IDs (which use single-character prefixes like s- and i-).
+ *
+ * @param id - The OpenSpec ID to parse (e.g., "os-a1b2" or "osc-c3d4")
+ * @returns Parsed ID components, or null if invalid format
+ *
+ * @example
+ * parseOpenSpecId("os-a1b2")
+ * // Returns: { type: "spec", name: "", hash: "a1b2", prefix: "os" }
+ *
+ * parseOpenSpecId("osc-c3d4")
+ * // Returns: { type: "change", name: "", hash: "c3d4", prefix: "osc" }
+ *
+ * parseOpenSpecId("invalid")
+ * // Returns: null
+ *
+ * parseOpenSpecId("s-abcd")
+ * // Returns: null (sudocode format, not OpenSpec)
+ */
+export function parseOpenSpecId(id) {
+    if (!id || typeof id !== "string") {
+        return null;
+    }
+    // Match pattern: prefix-hash where prefix is at least 2 characters
+    // This distinguishes OpenSpec IDs (os-, osc-) from sudocode IDs (s-, i-)
+    const match = id.match(/^([a-z]{2,})-([0-9a-f]{4,})$/i);
+    if (!match) {
+        return null;
+    }
+    const [, prefix, hash] = match;
+    const normalizedPrefix = prefix.toLowerCase();
+    // Determine type based on prefix
+    // Default change prefix is "osc", default spec prefix is "os"
+    // For custom prefixes, we use "osc" as the canonical change prefix
+    const isChange = normalizedPrefix === DEFAULT_CHANGE_PREFIX;
+    return {
+        type: isChange ? "change" : "spec",
+        name: "", // Cannot recover name from hash - must be looked up
+        hash: hash.toLowerCase(),
+        prefix: normalizedPrefix,
+    };
+}
+/**
+ * Verify that a given ID matches the expected ID for a name.
+ *
+ * Useful for validating that an ID was generated correctly.
+ *
+ * @param id - The ID to verify
+ * @param name - The name that should produce this ID
+ * @param type - Entity type ('spec' or 'change')
+ * @returns True if the ID matches what would be generated from the name
+ *
+ * @example
+ * verifyOpenSpecId("os-a1b2", "cli-init", "spec") // true or false
+ */
+export function verifyOpenSpecId(id, name, type) {
+    const parsed = parseOpenSpecId(id);
+    if (!parsed) {
+        return false;
+    }
+    const expectedId = type === "spec"
+        ? generateSpecId(name, parsed.prefix)
+        : generateChangeId(name, parsed.prefix);
+    return id.toLowerCase() === expectedId.toLowerCase();
+}
+/**
+ * Check if a string is a valid OpenSpec ID format.
+ *
+ * @param id - The string to check
+ * @returns True if the string matches OpenSpec ID format
+ *
+ * @example
+ * isOpenSpecId("os-a1b2")  // true
+ * isOpenSpecId("osc-c3d4") // true
+ * isOpenSpecId("invalid")  // false
+ * isOpenSpecId("s-abcd")   // false (sudocode format, not OpenSpec)
+ */
+export function isOpenSpecId(id) {
+    return parseOpenSpecId(id) !== null;
+}
+//# sourceMappingURL=id-generator.js.map

package/dist/id-generator.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenSpec Integration Plugin for sudocode
+ *
+ * Provides integration with OpenSpec - a standardized specification format
+ * for AI-assisted development. Syncs specs and issues to sudocode.
+ */
+import type { IntegrationPlugin } from "@sudocode-ai/types";
+/**
+ * OpenSpec specific configuration options
+ */
+export interface OpenSpecOptions {
+    /** Path to the OpenSpec directory (relative to project root) */
+    path: string;
+    /** Prefix for spec IDs imported from OpenSpec (default: "os") */
+    spec_prefix?: string;
+    /** Prefix for issue IDs imported from OpenSpec (default: "osi") */
+    issue_prefix?: string;
+}
+/**
+ * OpenSpec integration plugin
+ */
+declare const openSpecPlugin: IntegrationPlugin;
+export default openSpecPlugin;
+export { generateSpecId, generateChangeId, parseOpenSpecId, verifyOpenSpecId, isOpenSpecId, DEFAULT_SPEC_PREFIX, DEFAULT_CHANGE_PREFIX, type ParsedOpenSpecId, } from "./id-generator.js";
+export { parseSpecFile, extractCapability, parseRequirements, parseScenarios, parseGivenWhenThen, SPEC_PATTERNS, type ParsedOpenSpecSpec, type ParsedRequirement, type ParsedScenario, } from "./parser/spec-parser.js";
+export { parseTasks, parseTasksContent, getAllTasks, getIncompleteTasks, getTaskStats, calculateCompletionPercentage, isTasksFile, TASK_PATTERNS, type ParsedTask, type ParsedTasksFile, } from "./parser/tasks-parser.js";
+export { parseChangeDirectory, extractChangeName, detectArchiveStatus, parseProposal, extractTitleFromWhatChanges, formatTitle, parseChangeTasks, scanAffectedSpecs, isChangeDirectory, scanChangeDirectories, parseAllChanges, CHANGE_PATTERNS, type ParsedOpenSpecChange, } from "./parser/change-parser.js";
+export { OpenSpecWatcher, type OpenSpecWatcherOptions, type ChangeCallback, } from "./watcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,iBAAiB,EASlB,MAAM,oBAAoB,CAAC;AAqB5B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+BD;;GAEG;AACH,QAAA,MAAM,cAAc,EAAE,iBA6FrB,CAAC;AAqqBF,eAAe,cAAc,CAAC;AAG9B,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,6BAA6B,EAC7B,WAAW,EACX,aAAa,EACb,KAAK,UAAU,EACf,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,2BAA2B,EAC3B,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}