specweave 0.28.17 → 0.28.19

package/dist/src/utils/chalk-fallback.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Chalk Fallback Utility
+ *
+ * Provides chalk-like API for colored console output with graceful fallback
+ * to plain text when chalk is not available (e.g., in marketplace plugins).
+ *
+ * This enables AC test validator to work in both:
+ * 1. Full npm-installed environments (uses real chalk)
+ * 2. Marketplace plugin environments (uses ANSI codes or plain text)
+ */
+type ChalkInput = string | number;
+interface ChalkFn {
+    (text: ChalkInput): string;
+    bold: ChalkFn;
+}
+interface ChalkInstance {
+    red: ChalkFn;
+    green: ChalkFn;
+    yellow: ChalkFn;
+    blue: ChalkFn;
+    gray: ChalkFn;
+    bold: ChalkFn & {
+        (text: string): string;
+    };
+}
+/**
+ * Chalk-compatible API using ANSI codes
+ * Falls back to plain text if terminal doesn't support colors
+ */
+export declare const chalkFallback: ChalkInstance;
+export declare function getChalk(): Promise<ChalkInstance>;
+/**
+ * Synchronous chalk getter - uses fallback if chalk wasn't pre-loaded
+ * Call getChalk() at module init to try loading real chalk first
+ */
+export declare function getChalkSync(): ChalkInstance;
+export default chalkFallback;
+//# sourceMappingURL=chalk-fallback.d.ts.map

package/dist/src/utils/chalk-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chalk-fallback.d.ts","sourceRoot":"","sources":["../../../src/utils/chalk-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAoClC,UAAU,OAAO;IACf,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,GAAG;QACd,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,aAoB3B,CAAC;AAqBF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,CAavD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,aAAa,CAE5C;AAED,eAAe,aAAa,CAAC"}

package/dist/src/utils/chalk-fallback.js

@@ -0,0 +1,118 @@
+/**
+ * Chalk Fallback Utility
+ *
+ * Provides chalk-like API for colored console output with graceful fallback
+ * to plain text when chalk is not available (e.g., in marketplace plugins).
+ *
+ * This enables AC test validator to work in both:
+ * 1. Full npm-installed environments (uses real chalk)
+ * 2. Marketplace plugin environments (uses ANSI codes or plain text)
+ */
+// Simple ANSI color codes for terminal output
+const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    gray: '\x1b[90m',
+};
+// Check if we're in a TTY that supports colors
+const supportsColor = process.stdout?.isTTY ?? false;
+/**
+ * Creates a chalk-like color function
+ */
+function createColorFn(colorCode) {
+    const fn = ((text) => {
+        const str = String(text);
+        if (!supportsColor)
+            return str;
+        return `${colorCode}${str}${ANSI.reset}`;
+    });
+    // Add chainable modifiers
+    fn.bold = ((text) => {
+        const str = String(text);
+        if (!supportsColor)
+            return str;
+        return `${ANSI.bold}${colorCode}${str}${ANSI.reset}`;
+    });
+    return fn;
+}
+/**
+ * Creates a bold color function
+ */
+function createBoldColorFn(colorCode) {
+    const fn = ((text) => {
+        const str = String(text);
+        if (!supportsColor)
+            return str;
+        return `${ANSI.bold}${colorCode}${str}${ANSI.reset}`;
+    });
+    fn.bold = fn;
+    return fn;
+}
+/**
+ * Chalk-compatible API using ANSI codes
+ * Falls back to plain text if terminal doesn't support colors
+ */
+export const chalkFallback = {
+    red: createColorFn(ANSI.red),
+    green: createColorFn(ANSI.green),
+    yellow: createColorFn(ANSI.yellow),
+    blue: createColorFn(ANSI.blue),
+    gray: createColorFn(ANSI.gray),
+    bold: Object.assign(((text) => {
+        const str = String(text);
+        if (!supportsColor)
+            return str;
+        return `${ANSI.bold}${str}${ANSI.reset}`;
+    }), {
+        bold: ((text) => {
+            const str = String(text);
+            if (!supportsColor)
+                return str;
+            return `${ANSI.bold}${str}${ANSI.reset}`;
+        }),
+    }),
+};
+// Add nested color methods to bold
+chalkFallback.bold.red = createBoldColorFn(ANSI.red);
+chalkFallback.bold.green = createBoldColorFn(ANSI.green);
+chalkFallback.bold.yellow = createBoldColorFn(ANSI.yellow);
+chalkFallback.bold.blue = createBoldColorFn(ANSI.blue);
+chalkFallback.bold.gray = createBoldColorFn(ANSI.gray);
+// Add bold method to color functions for chaining like chalk.green.bold()
+chalkFallback.red.bold = createBoldColorFn(ANSI.red);
+chalkFallback.green.bold = createBoldColorFn(ANSI.green);
+chalkFallback.yellow.bold = createBoldColorFn(ANSI.yellow);
+chalkFallback.blue.bold = createBoldColorFn(ANSI.blue);
+chalkFallback.gray.bold = createBoldColorFn(ANSI.gray);
+/**
+ * Try to import chalk, fall back to ANSI implementation
+ */
+let resolvedChalk = null;
+export async function getChalk() {
+    if (resolvedChalk)
+        return resolvedChalk;
+    try {
+        // Try to dynamically import chalk
+        const chalkModule = await import('chalk');
+        resolvedChalk = chalkModule.default;
+        return resolvedChalk;
+    }
+    catch {
+        // Chalk not available, use fallback
+        resolvedChalk = chalkFallback;
+        return resolvedChalk;
+    }
+}
+/**
+ * Synchronous chalk getter - uses fallback if chalk wasn't pre-loaded
+ * Call getChalk() at module init to try loading real chalk first
+ */
+export function getChalkSync() {
+    return resolvedChalk ?? chalkFallback;
+}
+export default chalkFallback;
+//# sourceMappingURL=chalk-fallback.js.map

package/dist/src/utils/chalk-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chalk-fallback.js","sourceRoot":"","sources":["../../../src/utils/chalk-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,8CAA8C;AAC9C,MAAM,IAAI,GAAG;IACX,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,UAAU;IACf,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF,+CAA+C;AAC/C,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,KAAK,CAAC;AAKrD;;GAEG;AACH,SAAS,aAAa,CAAC,SAAiB;IACtC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAgB,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,aAAa;YAAE,OAAO,GAAG,CAAC;QAC/B,OAAO,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3C,CAAC,CAAY,CAAC;IAEd,0BAA0B;IAC1B,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,IAAgB,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,aAAa;YAAE,OAAO,GAAG,CAAC;QAC/B,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC,CAAY,CAAC;IAEd,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,MAAM,EAAE,GAAG,CAAC,CAAC,IAAgB,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,aAAa;YAAE,OAAO,GAAG,CAAC;QAC/B,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IACvD,CAAC,CAAY,CAAC;IAEd,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC;IACb,OAAO,EAAE,CAAC;AACZ,CAAC;AAkBD;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,GAAG,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;IAC5B,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,CACjB,CAAC,CAAC,IAAgB,EAAE,EAAE;QACpB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,aAAa;YAAE,OAAO,GAAG,CAAC;QAC/B,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3C,CAAC,CAAY,EACb;QACE,IAAI,EAAE,CAAC,CAAC,IAAgB,EAAE,EAAE;YAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACzB,IAAI,CAAC,aAAa;gBAAE,OAAO,GAAG,CAAC;YAC/B,OAAO,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3C,CAAC,CAAY;KACd,CACF;CACF,CAAC;AAEF,mCAAmC;AAClC,aAAa,CAAC,IAAY,CAAC,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,aAAa,CAAC,IAAY,CAAC,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjE,aAAa,CAAC,IAAY,CAAC,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACnE,aAAa,CAAC,IAAY,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/D,aAAa,CAAC,IAAY,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEhE,0EAA0E;AAC1E,aAAa,CAAC,GAAG,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrD,aAAa,CAAC,KAAK,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACzD,aAAa,CAAC,MAAM,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,aAAa,CAAC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvD,aAAa,CAAC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEvD;;GAEG;AACH,IAAI,aAAa,GAAyB,IAAI,CAAC;AAE/C,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IAExC,IAAI,CAAC;QACH,kCAAkC;QAClC,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,aAAa,GAAG,WAAW,CAAC,OAAmC,CAAC;QAChE,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;QACpC,aAAa,GAAG,aAAa,CAAC;QAC9B,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,IAAI,aAAa,CAAC;AACxC,CAAC;AAED,eAAe,aAAa,CAAC"}

package/dist/src/utils/project-id-generator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Project ID Generator with Duplicate Prevention (v0.29.0+)
+ *
+ * Generates unique SpecWeave project IDs from external tool entities:
+ * - JIRA boards → Project IDs
+ * - ADO area paths → Project IDs
+ * - GitHub repos → Project IDs
+ *
+ * Handles collision detection and composite key generation.
+ */
+/**
+ * Project ID generation options
+ */
+export interface ProjectIdOptions {
+    /** External container (JIRA project key, ADO project name) */
+    externalContainer: string;
+    /** Local name (board name, area path, repo name) */
+    localName: string;
+    /** Provider type */
+    provider: 'jira' | 'ado' | 'github';
+    /** Existing project IDs to check for collisions */
+    existingIds?: string[];
+}
+/**
+ * Generated project ID result
+ */
+export interface ProjectIdResult {
+    /** Generated project ID */
+    id: string;
+    /** Whether collision was detected and prefix was added */
+    hadCollision: boolean;
+    /** Original local name before sanitization */
+    originalName: string;
+    /** Full composite key (container + local) */
+    compositeKey: string;
+}
+/**
+ * Normalize a string to a valid project ID
+ * - Lowercase
+ * - Replace spaces and special chars with hyphens
+ * - Remove consecutive hyphens
+ * - Remove leading/trailing hyphens
+ */
+export declare function normalizeToProjectId(name: string): string;
+/**
+ * Generate a short prefix from external container name
+ * Used when collision is detected
+ */
+export declare function generateContainerPrefix(container: string): string;
+/**
+ * Generate unique project ID with collision detection
+ *
+ * Algorithm:
+ * 1. Normalize local name to project ID format
+ * 2. Check if ID exists in existingIds
+ * 3. If collision, add container prefix: "core-fe" instead of "fe"
+ * 4. If still collision (rare), add numeric suffix: "core-fe-2"
+ *
+ * @param options Generation options
+ * @returns Generated project ID with metadata
+ */
+export declare function generateProjectId(options: ProjectIdOptions): ProjectIdResult;
+/**
+ * Batch generate project IDs from multiple sources
+ * Ensures no collisions within the batch and with existing IDs
+ */
+export declare function generateProjectIdsBatch(sources: Array<{
+    container: string;
+    localName: string;
+    provider: 'jira' | 'ado' | 'github';
+}>, existingIds?: string[]): Map<string, ProjectIdResult>;
+/**
+ * Get existing project IDs from a SpecWeave project
+ *
+ * @param projectRoot Path to project root
+ * @returns Array of existing project IDs
+ */
+export declare function getExistingProjectIds(projectRoot: string): string[];
+/**
+ * Create 2-level directory structure for JIRA/ADO projects
+ *
+ * Structure:
+ * .specweave/docs/internal/specs/
+ * ├── JIRA-CORE/                  (external container level)
+ * │   ├── fe/                     (SpecWeave project level)
+ * │   ├── be/
+ * │   └── mobile/
+ * └── ADO-MyProduct/
+ *     ├── fe/
+ *     └── be/
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID (JIRA project key or ADO project name)
+ * @param specweaveProjectId SpecWeave project ID
+ */
+export declare function createTwoLevelProjectDir(projectRoot: string, containerType: 'jira' | 'ado', containerId: string, specweaveProjectId: string): string;
+/**
+ * Get the 2-level path for a project
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID
+ * @param specweaveProjectId SpecWeave project ID
+ * @returns Full path or undefined if using flat structure
+ */
+export declare function getTwoLevelProjectPath(projectRoot: string, containerType: 'jira' | 'ado' | null, containerId: string | null, specweaveProjectId: string): string;
+/**
+ * Parse a 2-level project path to extract container and project info
+ *
+ * @param projectPath Path like ".specweave/docs/internal/specs/JIRA-CORE/fe"
+ * @returns Parsed container and project info
+ */
+export declare function parseTwoLevelPath(projectPath: string): {
+    containerType: 'jira' | 'ado' | null;
+    containerId: string | null;
+    projectId: string;
+} | null;
+/**
+ * Validate project ID format
+ */
+export declare function isValidProjectId(id: string): boolean;
+/**
+ * Suggest a valid project ID from an invalid one
+ */
+export declare function suggestProjectId(invalidId: string): string;
+//# sourceMappingURL=project-id-generator.d.ts.map

package/dist/src/utils/project-id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-id-generator.d.ts","sourceRoot":"","sources":["../../../src/utils/project-id-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAE1B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAEpC,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IAEtB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA6C5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAA;CAAE,CAAC,EAC7F,WAAW,GAAE,MAAM,EAAO,GACzB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAoB9B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAenE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GAAG,KAAK,EAC7B,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAoBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,EACpC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAwBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,aAAa,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAyBP;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/src/utils/project-id-generator.js

@@ -0,0 +1,228 @@
+/**
+ * Project ID Generator with Duplicate Prevention (v0.29.0+)
+ *
+ * Generates unique SpecWeave project IDs from external tool entities:
+ * - JIRA boards → Project IDs
+ * - ADO area paths → Project IDs
+ * - GitHub repos → Project IDs
+ *
+ * Handles collision detection and composite key generation.
+ */
+import * as fs from './fs-native.js';
+import * as path from 'path';
+/**
+ * Normalize a string to a valid project ID
+ * - Lowercase
+ * - Replace spaces and special chars with hyphens
+ * - Remove consecutive hyphens
+ * - Remove leading/trailing hyphens
+ */
+export function normalizeToProjectId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+        .replace(/-+/g, '-') // Remove consecutive hyphens
+        .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+/**
+ * Generate a short prefix from external container name
+ * Used when collision is detected
+ */
+export function generateContainerPrefix(container) {
+    // For JIRA project keys like "CORE", use as-is (already short)
+    if (/^[A-Z]{2,10}$/.test(container)) {
+        return container.toLowerCase();
+    }
+    // For longer names, create abbreviation
+    // "MyProduct" → "mp", "Backend-Services" → "bs"
+    const words = container.split(/[-_\s]+/);
+    if (words.length === 1) {
+        // Single word: use first 3 chars
+        return container.substring(0, 3).toLowerCase();
+    }
+    // Multiple words: use first letter of each
+    return words.map(w => w[0]).join('').toLowerCase();
+}
+/**
+ * Generate unique project ID with collision detection
+ *
+ * Algorithm:
+ * 1. Normalize local name to project ID format
+ * 2. Check if ID exists in existingIds
+ * 3. If collision, add container prefix: "core-fe" instead of "fe"
+ * 4. If still collision (rare), add numeric suffix: "core-fe-2"
+ *
+ * @param options Generation options
+ * @returns Generated project ID with metadata
+ */
+export function generateProjectId(options) {
+    const { externalContainer, localName, provider, existingIds = [] } = options;
+    // Step 1: Normalize local name
+    const baseId = normalizeToProjectId(localName);
+    const compositeKey = `${externalContainer}/${localName}`;
+    // Step 2: Check for collision
+    if (!existingIds.includes(baseId)) {
+        return {
+            id: baseId,
+            hadCollision: false,
+            originalName: localName,
+            compositeKey,
+        };
+    }
+    // Step 3: Collision detected - add container prefix
+    const prefix = generateContainerPrefix(externalContainer);
+    let prefixedId = `${prefix}-${baseId}`;
+    if (!existingIds.includes(prefixedId)) {
+        return {
+            id: prefixedId,
+            hadCollision: true,
+            originalName: localName,
+            compositeKey,
+        };
+    }
+    // Step 4: Still collision (rare) - add numeric suffix
+    let suffix = 2;
+    while (existingIds.includes(`${prefixedId}-${suffix}`)) {
+        suffix++;
+        if (suffix > 100) {
+            throw new Error(`Cannot generate unique ID for ${compositeKey} after 100 attempts`);
+        }
+    }
+    return {
+        id: `${prefixedId}-${suffix}`,
+        hadCollision: true,
+        originalName: localName,
+        compositeKey,
+    };
+}
+/**
+ * Batch generate project IDs from multiple sources
+ * Ensures no collisions within the batch and with existing IDs
+ */
+export function generateProjectIdsBatch(sources, existingIds = []) {
+    const results = new Map();
+    const allIds = [...existingIds];
+    for (const source of sources) {
+        const result = generateProjectId({
+            externalContainer: source.container,
+            localName: source.localName,
+            provider: source.provider,
+            existingIds: allIds,
+        });
+        // Add to tracking to prevent intra-batch collisions
+        allIds.push(result.id);
+        // Key by composite key for easy lookup
+        results.set(result.compositeKey, result);
+    }
+    return results;
+}
+/**
+ * Get existing project IDs from a SpecWeave project
+ *
+ * @param projectRoot Path to project root
+ * @returns Array of existing project IDs
+ */
+export function getExistingProjectIds(projectRoot) {
+    const specsDir = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs');
+    if (!fs.existsSync(specsDir)) {
+        return [];
+    }
+    try {
+        const entries = fs.readdirSync(specsDir, { withFileTypes: true });
+        return entries
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith('_'))
+            .map(entry => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Create 2-level directory structure for JIRA/ADO projects
+ *
+ * Structure:
+ * .specweave/docs/internal/specs/
+ * ├── JIRA-CORE/                  (external container level)
+ * │   ├── fe/                     (SpecWeave project level)
+ * │   ├── be/
+ * │   └── mobile/
+ * └── ADO-MyProduct/
+ *     ├── fe/
+ *     └── be/
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID (JIRA project key or ADO project name)
+ * @param specweaveProjectId SpecWeave project ID
+ */
+export function createTwoLevelProjectDir(projectRoot, containerType, containerId, specweaveProjectId) {
+    // Normalize container ID to directory-safe name
+    const containerDirName = `${containerType.toUpperCase()}-${normalizeToProjectId(containerId)}`;
+    const projectDirName = specweaveProjectId;
+    const fullPath = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', containerDirName, projectDirName);
+    if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+    }
+    return fullPath;
+}
+/**
+ * Get the 2-level path for a project
+ *
+ * @param projectRoot Path to project root
+ * @param containerType Type of external container
+ * @param containerId External container ID
+ * @param specweaveProjectId SpecWeave project ID
+ * @returns Full path or undefined if using flat structure
+ */
+export function getTwoLevelProjectPath(projectRoot, containerType, containerId, specweaveProjectId) {
+    // If no container type, use flat structure (GitHub or single project)
+    if (!containerType || !containerId) {
+        return path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', specweaveProjectId);
+    }
+    // 2-level structure for JIRA/ADO
+    const containerDirName = `${containerType.toUpperCase()}-${normalizeToProjectId(containerId)}`;
+    return path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', containerDirName, specweaveProjectId);
+}
+/**
+ * Parse a 2-level project path to extract container and project info
+ *
+ * @param projectPath Path like ".specweave/docs/internal/specs/JIRA-CORE/fe"
+ * @returns Parsed container and project info
+ */
+export function parseTwoLevelPath(projectPath) {
+    // Match pattern: .../specs/{CONTAINER-TYPE-ID}/{PROJECT-ID}
+    const match = projectPath.match(/specs[/\\]((?:JIRA|ADO)-([^/\\]+))[/\\]([^/\\]+)/);
+    if (!match) {
+        // Try flat structure: .../specs/{PROJECT-ID}
+        const flatMatch = projectPath.match(/specs[/\\]([^/\\]+)$/);
+        if (flatMatch) {
+            return {
+                containerType: null,
+                containerId: null,
+                projectId: flatMatch[1],
+            };
+        }
+        return null;
+    }
+    const [, containerDir, containerId, projectId] = match;
+    const containerType = containerDir.startsWith('JIRA-') ? 'jira' : 'ado';
+    return {
+        containerType,
+        containerId,
+        projectId,
+    };
+}
+/**
+ * Validate project ID format
+ */
+export function isValidProjectId(id) {
+    return /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(id);
+}
+/**
+ * Suggest a valid project ID from an invalid one
+ */
+export function suggestProjectId(invalidId) {
+    const suggestion = normalizeToProjectId(invalidId);
+    return suggestion || 'project';
+}
+//# sourceMappingURL=project-id-generator.js.map

package/dist/src/utils/project-id-generator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.17",
+  "version": "0.28.19",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",