@planu/cli 0.63.6 → 0.64.0

package/dist/engine/observability/noop-tracer.js

@@ -0,0 +1,41 @@
+// engine/observability/noop-tracer.ts — Zero-overhead Tracer implementation (SPEC-165)
+// Used when OTel is disabled (default). All methods are pure no-ops.
+// ---------------------------------------------------------------------------
+// NoopSpanHandle — no-op span with safe, idempotent methods
+// ---------------------------------------------------------------------------
+class NoopSpanHandle {
+    setAttribute(_key, _value) {
+        // no-op
+    }
+    recordError(_error) {
+        // no-op
+    }
+    end(_status) {
+        // no-op
+    }
+}
+// Reuse the same singleton to avoid GC pressure on hot paths.
+const NOOP_SPAN = new NoopSpanHandle();
+// ---------------------------------------------------------------------------
+// NoopTracer — satisfies the Tracer interface at zero cost
+// ---------------------------------------------------------------------------
+/**
+ * No-op tracer used when OTel is not configured.
+ * All methods are synchronous and return immediately.
+ * No memory allocations on hot paths (reuses NOOP_SPAN singleton).
+ */
+export class NoopTracer {
+    startSpan(_name, _attributes) {
+        return NOOP_SPAN;
+    }
+    startChildSpan(_name, _parent, _attributes) {
+        return NOOP_SPAN;
+    }
+    recordCounter(_name, _value, _attributes) {
+        // no-op
+    }
+    recordHistogram(_name, _value, _attributes) {
+        // no-op
+    }
+}
+//# sourceMappingURL=noop-tracer.js.map

package/dist/engine/observability/noop-tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-tracer.js","sourceRoot":"","sources":["../../../src/engine/observability/noop-tracer.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,qEAAqE;AAIrE,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E,MAAM,cAAc;IAClB,YAAY,CAAC,IAAY,EAAE,MAAiC;QAC1D,QAAQ;IACV,CAAC;IAED,WAAW,CAAC,MAAsB;QAChC,QAAQ;IACV,CAAC;IAED,GAAG,CAAC,OAAoB;QACtB,QAAQ;IACV,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,SAAS,GAAe,IAAI,cAAc,EAAE,CAAC;AAEnD,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACrB,SAAS,CAAC,KAAa,EAAE,WAA4B;QACnD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,cAAc,CACZ,KAAa,EACb,OAA0B,EAC1B,WAA4B;QAE5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,aAAa,CAAC,KAAa,EAAE,MAAe,EAAE,WAA4B;QACxE,QAAQ;IACV,CAAC;IAED,eAAe,CAAC,KAAa,EAAE,MAAc,EAAE,WAA4B;QACzE,QAAQ;IACV,CAAC;CACF"}

package/dist/engine/observability/otel-tracer.d.ts

@@ -0,0 +1,19 @@
+import type { SpanHandle, SpanAttributes, Tracer, OtelConfig } from '../../types/observability.js';
+/**
+ * OTel-backed tracer. Requires @opentelemetry/api to be installed at runtime.
+ * If the package is missing, falls back to NoopTracer silently.
+ */
+export declare class OtelTracer implements Tracer {
+    private readonly inner;
+    private constructor();
+    /**
+     * Factory method — performs dynamic import of @opentelemetry/api.
+     * Returns NoopTracer if the package is unavailable.
+     */
+    static create(config: OtelConfig): Promise<Tracer>;
+    startSpan(name: string, attributes?: SpanAttributes): SpanHandle;
+    startChildSpan(name: string, parent: SpanHandle | null, attributes?: SpanAttributes): SpanHandle;
+    recordCounter(name: string, value?: number, attributes?: SpanAttributes): void;
+    recordHistogram(name: string, value: number, attributes?: SpanAttributes): void;
+}
+//# sourceMappingURL=otel-tracer.d.ts.map

package/dist/engine/observability/otel-tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-tracer.d.ts","sourceRoot":"","sources":["../../../src/engine/observability/otel-tracer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EAEV,cAAc,EACd,MAAM,EACN,UAAU,EAGX,MAAM,8BAA8B,CAAC;AAmDtC;;;GAGG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,OAAO;IAIP;;;OAGG;WACU,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAwExD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,UAAU;IAIhE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,UAAU;IAIhG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI;IAI9E,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI;CAGhF"}

package/dist/engine/observability/otel-tracer.js

@@ -0,0 +1,134 @@
+// engine/observability/otel-tracer.ts — OTel-backed Tracer implementation (SPEC-165)
+// Wraps @opentelemetry/api via dynamic import (optional peer dependency).
+// Falls back to NoopTracer if the package is not installed.
+import { NoopTracer } from './noop-tracer.js';
+// ---------------------------------------------------------------------------
+// OtelSpanHandle — wraps a live OTel span
+// ---------------------------------------------------------------------------
+class OtelSpanHandle {
+    span;
+    statusCodes;
+    ended = false;
+    constructor(span, statusCodes) {
+        this.span = span;
+        this.statusCodes = statusCodes;
+    }
+    setAttribute(key, value) {
+        if (this.ended) {
+            return;
+        }
+        this.span.setAttribute(key, value);
+    }
+    recordError(error) {
+        if (this.ended) {
+            return;
+        }
+        const err = typeof error === 'string' ? { message: error } : error;
+        this.span.recordException(err);
+        this.span.setStatus({ code: this.statusCodes.ERROR, message: err.message });
+    }
+    end(status) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        if (status === 'ok') {
+            this.span.setStatus({ code: this.statusCodes.OK });
+        }
+        else if (status === 'error') {
+            this.span.setStatus({ code: this.statusCodes.ERROR });
+        }
+        this.span.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// OtelTracer — real tracer backed by @opentelemetry/api
+// ---------------------------------------------------------------------------
+/**
+ * OTel-backed tracer. Requires @opentelemetry/api to be installed at runtime.
+ * If the package is missing, falls back to NoopTracer silently.
+ */
+export class OtelTracer {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Factory method — performs dynamic import of @opentelemetry/api.
+     * Returns NoopTracer if the package is unavailable.
+     */
+    static async create(config) {
+        let api;
+        try {
+            // Dynamic import — optional peer dep, zero hard coupling
+            api = (await import('@opentelemetry/api'));
+        }
+        catch {
+            // @opentelemetry/api not installed — graceful fallback
+            return new NoopTracer();
+        }
+        if (!config.enabled || !config.endpoint) {
+            return new NoopTracer();
+        }
+        const apiTracer = api.trace.getTracer(config.serviceName, config.serviceVersion);
+        const statusCodes = api.SpanStatusCode;
+        const realTracer = {
+            startSpan(name, attributes) {
+                const span = apiTracer.startSpan(name, { attributes });
+                const handle = new OtelSpanHandle(span, statusCodes);
+                if (attributes) {
+                    for (const [k, v] of Object.entries(attributes)) {
+                        handle.setAttribute(k, v);
+                    }
+                }
+                return handle;
+            },
+            startChildSpan(name, parent, attributes) {
+                // LIMITATION: @opentelemetry/api context propagation requires async context
+                // (AsyncLocalStorage / AsyncResource) which is not wired here.
+                // Instead we record a `parent.span.name` attribute so traces can be linked
+                // in the backend via attribute-based queries.
+                // Full W3C trace-context propagation is tracked as future work.
+                const enrichedAttributes = {
+                    ...attributes,
+                    ...(parent !== null ? { 'parent.linked': true } : {}),
+                };
+                const span = apiTracer.startSpan(name, { attributes: enrichedAttributes });
+                const handle = new OtelSpanHandle(span, statusCodes);
+                for (const [k, v] of Object.entries(enrichedAttributes)) {
+                    handle.setAttribute(k, v);
+                }
+                return handle;
+            },
+            recordCounter(name, value = 1, attributes) {
+                // @opentelemetry/sdk-metrics is not a hard dependency.
+                // Record as a short-lived span so the metric is captured in the trace backend.
+                const span = apiTracer.startSpan(`counter:${name}`, {
+                    attributes: { 'metric.value': value, ...attributes },
+                });
+                span.end();
+            },
+            recordHistogram(name, value, attributes) {
+                // Same approach — histogram observation recorded as a short-lived span.
+                const span = apiTracer.startSpan(`histogram:${name}`, {
+                    attributes: { 'metric.value': value, ...attributes },
+                });
+                span.end();
+            },
+        };
+        return new OtelTracer(realTracer);
+    }
+    startSpan(name, attributes) {
+        return this.inner.startSpan(name, attributes);
+    }
+    startChildSpan(name, parent, attributes) {
+        return this.inner.startChildSpan(name, parent, attributes);
+    }
+    recordCounter(name, value, attributes) {
+        this.inner.recordCounter(name, value, attributes);
+    }
+    recordHistogram(name, value, attributes) {
+        this.inner.recordHistogram(name, value, attributes);
+    }
+}
+//# sourceMappingURL=otel-tracer.js.map

package/dist/engine/observability/otel-tracer.js.map

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

package/dist/engine/observability/span-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { SpanHandle, SpanAttributes } from '../../types/observability.js';
+/**
+ * Starts a root span for a tool call.
+ * Attributes include toolName, inputSize, and any extra attrs provided.
+ *
+ * Usage:
+ *   const span = startToolSpan('create_spec', { projectId: 'abc' });
+ *   // ... do work ...
+ *   span.end('ok');
+ */
+export declare function startToolSpan(toolName: string, extraAttributes?: SpanAttributes): SpanHandle;
+/**
+ * Starts a span representing a spec lifecycle event (e.g. status transition).
+ * Intended to be used as a child of a per-spec root trace.
+ *
+ * @param specId  The spec identifier, e.g. "SPEC-042"
+ * @param event   A lifecycle event name, e.g. "draft_to_approved"
+ * @param parent  Parent span handle (the per-spec root span). May be null.
+ * @param extraAttributes  Additional attributes.
+ */
+export declare function startSpecLifecycleSpan(specId: string, event: string, parent: SpanHandle | null, extraAttributes?: SpanAttributes): SpanHandle;
+/**
+ * Runs `fn` inside a tool span, automatically recording duration and status.
+ * Returns the result of `fn`.
+ * If `fn` throws, records the error on the span, ends it with 'error', then re-throws.
+ */
+export declare function withToolSpan<T>(toolName: string, fn: (span: SpanHandle) => Promise<T> | T, extraAttributes?: SpanAttributes): Promise<T>;
+//# sourceMappingURL=span-helpers.d.ts.map

package/dist/engine/observability/span-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-helpers.d.ts","sourceRoot":"","sources":["../../../src/engine/observability/span-helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAO/E;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,cAAc,GAAG,UAAU,CAM5F;AAMD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,eAAe,CAAC,EAAE,cAAc,GAC/B,UAAU,CAOZ;AAMD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxC,eAAe,CAAC,EAAE,cAAc,GAC/B,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/engine/observability/span-helpers.js

@@ -0,0 +1,68 @@
+// engine/observability/span-helpers.ts — High-level span helpers (SPEC-165)
+// Provides domain-specific wrappers over the raw Tracer interface.
+import { getTracer } from './tracer.js';
+// ---------------------------------------------------------------------------
+// Tool spans
+// ---------------------------------------------------------------------------
+/**
+ * Starts a root span for a tool call.
+ * Attributes include toolName, inputSize, and any extra attrs provided.
+ *
+ * Usage:
+ *   const span = startToolSpan('create_spec', { projectId: 'abc' });
+ *   // ... do work ...
+ *   span.end('ok');
+ */
+export function startToolSpan(toolName, extraAttributes) {
+    const attrs = {
+        'tool.name': toolName,
+        ...extraAttributes,
+    };
+    return getTracer().startSpan(`tool/${toolName}`, attrs);
+}
+// ---------------------------------------------------------------------------
+// Spec lifecycle spans
+// ---------------------------------------------------------------------------
+/**
+ * Starts a span representing a spec lifecycle event (e.g. status transition).
+ * Intended to be used as a child of a per-spec root trace.
+ *
+ * @param specId  The spec identifier, e.g. "SPEC-042"
+ * @param event   A lifecycle event name, e.g. "draft_to_approved"
+ * @param parent  Parent span handle (the per-spec root span). May be null.
+ * @param extraAttributes  Additional attributes.
+ */
+export function startSpecLifecycleSpan(specId, event, parent, extraAttributes) {
+    const attrs = {
+        'spec.id': specId,
+        'spec.event': event,
+        ...extraAttributes,
+    };
+    return getTracer().startChildSpan(`spec/${specId}/${event}`, parent, attrs);
+}
+// ---------------------------------------------------------------------------
+// Instrumented execution helper
+// ---------------------------------------------------------------------------
+/**
+ * Runs `fn` inside a tool span, automatically recording duration and status.
+ * Returns the result of `fn`.
+ * If `fn` throws, records the error on the span, ends it with 'error', then re-throws.
+ */
+export async function withToolSpan(toolName, fn, extraAttributes) {
+    const start = Date.now();
+    const span = startToolSpan(toolName, extraAttributes);
+    try {
+        const result = await fn(span);
+        span.setAttribute('tool.duration_ms', Date.now() - start);
+        span.end('ok');
+        return result;
+    }
+    catch (error) {
+        span.setAttribute('tool.duration_ms', Date.now() - start);
+        const message = error instanceof Error ? error.message : String(error);
+        span.recordError(message);
+        span.end('error');
+        throw error;
+    }
+}
+//# sourceMappingURL=span-helpers.js.map

package/dist/engine/observability/span-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-helpers.js","sourceRoot":"","sources":["../../../src/engine/observability/span-helpers.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,mEAAmE;AAGnE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,eAAgC;IAC9E,MAAM,KAAK,GAAmB;QAC5B,WAAW,EAAE,QAAQ;QACrB,GAAG,eAAe;KACnB,CAAC;IACF,OAAO,SAAS,EAAE,CAAC,SAAS,CAAC,QAAQ,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,KAAa,EACb,MAAyB,EACzB,eAAgC;IAEhC,MAAM,KAAK,GAAmB;QAC5B,SAAS,EAAE,MAAM;QACjB,YAAY,EAAE,KAAK;QACnB,GAAG,eAAe;KACnB,CAAC;IACF,OAAO,SAAS,EAAE,CAAC,cAAc,CAAC,QAAQ,MAAM,IAAI,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,EAAwC,EACxC,eAAgC;IAEhC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,YAAY,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;QAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,CAAC,YAAY,CAAC,kBAAkB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/engine/observability/tracer.d.ts

@@ -0,0 +1,26 @@
+import type { Tracer, OtelConfig } from '../../types/observability.js';
+/**
+ * Returns the active global tracer.
+ * Defaults to NoopTracer — zero overhead when not configured.
+ */
+export declare function getTracer(): Tracer;
+/**
+ * Initializes the global tracer from an OtelConfig.
+ * If enabled=false or no endpoint, installs NoopTracer.
+ * If enabled=true, attempts to build an OtelTracer (requires @opentelemetry/api).
+ * Falls back to NoopTracer if the package is not installed.
+ *
+ * This function is async because OtelTracer performs a dynamic import.
+ */
+export declare function initTracer(config: OtelConfig): Promise<void>;
+/**
+ * Replaces the active tracer with the provided instance.
+ * Primarily for testing — allows injecting a custom or spy tracer.
+ */
+export declare function setTracer(tracer: Tracer): void;
+/**
+ * Resets the global tracer to NoopTracer.
+ * Call in test afterEach/teardown to avoid state leakage.
+ */
+export declare function resetTracer(): void;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/engine/observability/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/engine/observability/tracer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAUvE;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/engine/observability/tracer.js

@@ -0,0 +1,45 @@
+// engine/observability/tracer.ts — Active tracer singleton + lifecycle (SPEC-165)
+// Provides the global Tracer instance. Defaults to NoopTracer until configured.
+import { NoopTracer } from './noop-tracer.js';
+import { OtelTracer } from './otel-tracer.js';
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let _tracer = new NoopTracer();
+/**
+ * Returns the active global tracer.
+ * Defaults to NoopTracer — zero overhead when not configured.
+ */
+export function getTracer() {
+    return _tracer;
+}
+/**
+ * Initializes the global tracer from an OtelConfig.
+ * If enabled=false or no endpoint, installs NoopTracer.
+ * If enabled=true, attempts to build an OtelTracer (requires @opentelemetry/api).
+ * Falls back to NoopTracer if the package is not installed.
+ *
+ * This function is async because OtelTracer performs a dynamic import.
+ */
+export async function initTracer(config) {
+    if (!config.enabled || !config.endpoint) {
+        _tracer = new NoopTracer();
+        return;
+    }
+    _tracer = await OtelTracer.create(config);
+}
+/**
+ * Replaces the active tracer with the provided instance.
+ * Primarily for testing — allows injecting a custom or spy tracer.
+ */
+export function setTracer(tracer) {
+    _tracer = tracer;
+}
+/**
+ * Resets the global tracer to NoopTracer.
+ * Call in test afterEach/teardown to avoid state leakage.
+ */
+export function resetTracer() {
+    _tracer = new NoopTracer();
+}
+//# sourceMappingURL=tracer.js.map

package/dist/engine/observability/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../../src/engine/observability/tracer.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,gFAAgF;AAGhF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,IAAI,OAAO,GAAW,IAAI,UAAU,EAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAkB;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxC,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;AAC7B,CAAC"}

package/dist/engine/rbac/index.d.ts

@@ -0,0 +1,3 @@
+export { ROLE_PERMISSIONS, ROLE_DESCRIPTIONS, roleHasPermission, listRoles } from './roles.js';
+export { checkPermission, resolveRole, buildAuditEntry } from './permission-checker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/rbac/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/rbac/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/engine/rbac/index.js

@@ -0,0 +1,4 @@
+// engine/rbac/index.ts — Barrel export for SPEC-166 RBAC engine module
+export { ROLE_PERMISSIONS, ROLE_DESCRIPTIONS, roleHasPermission, listRoles } from './roles.js';
+export { checkPermission, resolveRole, buildAuditEntry } from './permission-checker.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/rbac/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/rbac/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/engine/rbac/permission-checker.d.ts

@@ -0,0 +1,21 @@
+import type { RbacConfig, RbacRole, PermissionAction, PermissionResult, RbacAuditEntry } from '../../types/index.js';
+/**
+ * Check whether a user is allowed to perform an action on a resource.
+ *
+ * When RBAC is disabled (default single-user mode) this is always a no-op
+ * that returns allowed=true — preserving backward compatibility.
+ *
+ * Resolution order:
+ *   1. RBAC disabled → allow
+ *   2. Find spec-scoped assignment (most specific)
+ *   3. Find project-level assignment
+ *   4. No assignment found → deny
+ */
+export declare function checkPermission(config: RbacConfig, userId: string, action: PermissionAction, resource: string, specId?: string): PermissionResult;
+/**
+ * Resolve the effective role for a user.
+ * Spec-scoped assignments take precedence over project-level assignments.
+ */
+export declare function resolveRole(config: RbacConfig, userId: string, specId?: string): RbacRole | undefined;
+export declare function buildAuditEntry(userId: string, action: PermissionAction, resource: string, result: PermissionResult, specId?: string): RbacAuditEntry;
+//# sourceMappingURL=permission-checker.d.ts.map

package/dist/engine/rbac/permission-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-checker.d.ts","sourceRoot":"","sources":["../../../src/engine/rbac/permission-checker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EAER,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAO9B;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,gBAAgB,CAwBlB;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,QAAQ,GAAG,SAAS,CActB;AAMD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAUhB"}

package/dist/engine/rbac/permission-checker.js

@@ -0,0 +1,74 @@
+// engine/rbac/permission-checker.ts — Permission enforcement logic for SPEC-166
+import { roleHasPermission } from './roles.js';
+// ---------------------------------------------------------------------------
+// Permission check
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a user is allowed to perform an action on a resource.
+ *
+ * When RBAC is disabled (default single-user mode) this is always a no-op
+ * that returns allowed=true — preserving backward compatibility.
+ *
+ * Resolution order:
+ *   1. RBAC disabled → allow
+ *   2. Find spec-scoped assignment (most specific)
+ *   3. Find project-level assignment
+ *   4. No assignment found → deny
+ */
+export function checkPermission(config, userId, action, resource, specId) {
+    // No-op when RBAC is not enabled
+    if (!config.enabled) {
+        return { allowed: true, reason: 'RBAC disabled — single-user mode' };
+    }
+    const role = resolveRole(config, userId, specId);
+    if (!role) {
+        const result = {
+            allowed: false,
+            reason: `User "${userId}" has no role assignment for this project${specId ? ` or spec "${specId}"` : ''}.`,
+        };
+        return result;
+    }
+    const allowed = roleHasPermission(role, action);
+    return {
+        allowed,
+        role,
+        reason: allowed
+            ? `Role "${role}" is permitted to perform "${action}" on "${resource}".`
+            : `Role "${role}" is not permitted to perform "${action}" on "${resource}".`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Role resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective role for a user.
+ * Spec-scoped assignments take precedence over project-level assignments.
+ */
+export function resolveRole(config, userId, specId) {
+    const assignments = config.assignments.filter((a) => a.userId === userId);
+    // 1. Spec-scoped (most specific)
+    if (specId) {
+        const specAssignment = assignments.find((a) => a.specId === specId);
+        if (specAssignment) {
+            return specAssignment.role;
+        }
+    }
+    // 2. Project-level (no specId)
+    const projectAssignment = assignments.find((a) => !a.specId);
+    return projectAssignment?.role;
+}
+// ---------------------------------------------------------------------------
+// Audit log entry builder
+// ---------------------------------------------------------------------------
+export function buildAuditEntry(userId, action, resource, result, specId) {
+    return {
+        timestamp: new Date().toISOString(),
+        userId,
+        action,
+        resource,
+        specId,
+        result: result.allowed ? 'allowed' : 'denied',
+        role: result.role,
+    };
+}
+//# sourceMappingURL=permission-checker.js.map

package/dist/engine/rbac/permission-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-checker.js","sourceRoot":"","sources":["../../../src/engine/rbac/permission-checker.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAUhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAkB,EAClB,MAAc,EACd,MAAwB,EACxB,QAAgB,EAChB,MAAe;IAEf,iCAAiC;IACjC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;IACvE,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,MAAM,GAAqB;YAC/B,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,SAAS,MAAM,4CAA4C,MAAM,CAAC,CAAC,CAAC,aAAa,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG;SAC3G,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,OAAO;QACL,OAAO;QACP,IAAI;QACJ,MAAM,EAAE,OAAO;YACb,CAAC,CAAC,SAAS,IAAI,8BAA8B,MAAM,SAAS,QAAQ,IAAI;YACxE,CAAC,CAAC,SAAS,IAAI,kCAAkC,MAAM,SAAS,QAAQ,IAAI;KAC/E,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,MAAkB,EAClB,MAAc,EACd,MAAe;IAEf,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAE1F,iCAAiC;IACjC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACpF,IAAI,cAAc,EAAE,CAAC;YACnB,OAAO,cAAc,CAAC,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,MAAM,iBAAiB,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC7E,OAAO,iBAAiB,EAAE,IAAI,CAAC;AACjC,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,MAAwB,EACxB,QAAgB,EAChB,MAAwB,EACxB,MAAe;IAEf,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,MAAM;QACN,MAAM;QACN,QAAQ;QACR,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QAC7C,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC;AACJ,CAAC"}

package/dist/engine/rbac/roles.d.ts

@@ -0,0 +1,12 @@
+import type { RbacRole, PermissionAction } from '../../types/index.js';
+/**
+ * Permissions granted to each role.
+ * All roles implicitly support 'read' — it is always included.
+ */
+export declare const ROLE_PERMISSIONS: Readonly<Record<RbacRole, ReadonlySet<PermissionAction>>>;
+export declare const ROLE_DESCRIPTIONS: Readonly<Record<RbacRole, string>>;
+/** Returns true if the given role has the requested permission on any resource. */
+export declare function roleHasPermission(role: RbacRole, action: PermissionAction): boolean;
+/** Returns all roles defined in the system. */
+export declare function listRoles(): RbacRole[];
+//# sourceMappingURL=roles.d.ts.map

package/dist/engine/rbac/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../src/engine/rbac/roles.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAMvE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAM7E,CAAC;AAMX,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAOvD,CAAC;AAMX,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEnF;AAED,+CAA+C;AAC/C,wBAAgB,SAAS,IAAI,QAAQ,EAAE,CAEtC"}

package/dist/engine/rbac/roles.js

@@ -0,0 +1,37 @@
+// engine/rbac/roles.ts — Role definitions and permission sets for SPEC-166
+// ---------------------------------------------------------------------------
+// Role permission matrix
+// ---------------------------------------------------------------------------
+/**
+ * Permissions granted to each role.
+ * All roles implicitly support 'read' — it is always included.
+ */
+export const ROLE_PERMISSIONS = {
+    Admin: new Set(['create', 'read', 'update', 'delete', 'approve', 'implement', 'configure']),
+    Architect: new Set(['create', 'read', 'update', 'approve', 'configure']),
+    Developer: new Set(['read', 'update', 'implement']),
+    Reviewer: new Set(['read', 'approve']),
+    Observer: new Set(['read']),
+};
+// ---------------------------------------------------------------------------
+// Role hierarchy (for display / description purposes)
+// ---------------------------------------------------------------------------
+export const ROLE_DESCRIPTIONS = {
+    Admin: 'Full access to all operations: create, read, update, delete, approve, implement, configure.',
+    Architect: 'Can create/approve specs and configure the project constitution.',
+    Developer: 'Can read specs and implement (update) them.',
+    Reviewer: 'Can read and approve/reject specs.',
+    Observer: 'Read-only access to all specs and project data.',
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Returns true if the given role has the requested permission on any resource. */
+export function roleHasPermission(role, action) {
+    return ROLE_PERMISSIONS[role].has(action);
+}
+/** Returns all roles defined in the system. */
+export function listRoles() {
+    return Object.keys(ROLE_PERMISSIONS);
+}
+//# sourceMappingURL=roles.js.map

package/dist/engine/rbac/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../../src/engine/rbac/roles.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAI3E,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8D;IACzF,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IAC3F,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IACxE,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACnD,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;CACnB,CAAC;AAEX,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACnE,KAAK,EACH,6FAA6F;IAC/F,SAAS,EAAE,kEAAkE;IAC7E,SAAS,EAAE,6CAA6C;IACxD,QAAQ,EAAE,oCAAoC;IAC9C,QAAQ,EAAE,iDAAiD;CACnD,CAAC;AAEX,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,MAAwB;IACxE,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,SAAS;IACvB,OAAO,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAe,CAAC;AACrD,CAAC"}

package/dist/engine/shared/ac-extractor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extract acceptance criteria text lines from spec markdown content.
+ * Detects the "Acceptance Criteria" / "Criterios de Aceptación" section header
+ * and collects checklist items (`- [ ] ...` or `- [x] ...`).
+ *
+ * Returns plain text strings (checkbox prefix stripped).
+ */
+export declare function extractAcceptanceCriteria(content: string): string[];
+//# sourceMappingURL=ac-extractor.d.ts.map

package/dist/engine/shared/ac-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ac-extractor.d.ts","sourceRoot":"","sources":["../../../src/engine/shared/ac-extractor.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BnE"}

package/dist/engine/shared/ac-extractor.js

@@ -0,0 +1,36 @@
+// engine/shared/ac-extractor.ts — Shared acceptance criteria extraction utility
+// Used by: spec-versioning/differ.ts, living-spec/auto-updater.ts, spec-decomposer/analyzer.ts
+/**
+ * Extract acceptance criteria text lines from spec markdown content.
+ * Detects the "Acceptance Criteria" / "Criterios de Aceptación" section header
+ * and collects checklist items (`- [ ] ...` or `- [x] ...`).
+ *
+ * Returns plain text strings (checkbox prefix stripped).
+ */
+export function extractAcceptanceCriteria(content) {
+    const criteria = [];
+    const lines = content.split('\n');
+    let inAcSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Detect AC section header
+        if (/^#+\s*(acceptance criteria|criterios de aceptaci[oó]n)/i.test(trimmed)) {
+            inAcSection = true;
+            continue;
+        }
+        // Exit AC section on next major header (that is not another AC header)
+        if (inAcSection && /^#+\s/.test(trimmed) && !/^#+\s*(acceptance|criterio)/i.test(trimmed)) {
+            inAcSection = false;
+            continue;
+        }
+        // Collect checklist items in AC section
+        if (inAcSection && /^-\s*\[[ xX]\]/.test(trimmed)) {
+            const text = trimmed.replace(/^-\s*\[[ xX]\]\s*/, '').trim();
+            if (text.length > 0) {
+                criteria.push(text);
+            }
+        }
+    }
+    return criteria;
+}
+//# sourceMappingURL=ac-extractor.js.map