@codewalla_india/openspec 1.1.0 → 1.3.0

package/dist/telemetry/index.d.ts

@@ -1,13 +1,17 @@
+import type { CommandTelemetryContext } from './command-context.js';
 export declare function canSendTelemetry(): Promise<boolean>;
 export { TelemetryIdentityRequiredError, buildIdentityRequiredMessage, resolveTelemetryUserId, requireTelemetryIdentity, setupTelemetryIdentity, promptAndStoreTelemetryIdentity, getIdentityFilePath, validateUserId, ensureTelemetryIdentity, } from './identity.js';
 export { DEFAULT_POSTHOG_KEY, DEFAULT_POSTHOG_HOST, safeTelemetryFetch } from './client.js';
-export { sanitizeWorkflowInput, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, type WorkflowEditor, } from './input.js';
-export declare function trackCommand(commandName: string, version: string): Promise<void>;
+export { sanitizeWorkflowInput, sanitizeTelemetryContent, readSanitizedFile, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, MAX_ARTIFACT_BODY_LENGTH, type WorkflowEditor, } from './input.js';
+export { resolveTelemetryCommandPath, buildCommandTelemetryContext, type CommandTelemetryContext, type CommandCategory, } from './command-context.js';
+export { resolveCaller } from './caller.js';
+export declare function trackCommand(commandName: string, version: string, context?: CommandTelemetryContext): Promise<void>;
 export declare function trackEvent(event: string, properties?: Record<string, unknown>): Promise<void>;
 export declare function trackCommandFailed(command: string, error: unknown, errorCode?: string): Promise<void>;
 export declare function shutdown(): Promise<void>;
 /** @internal Test helper */
 export declare function resetTelemetryForTests(): void;
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackComprehensionRetakeRequired, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 export type { EntryPoint } from './marker.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -3,26 +3,34 @@
  */
 import { resolveTelemetryUserId } from './identity.js';
 import { captureEvent, shutdownClient, resetTelemetryClientForTests } from './client.js';
+import { sanitizeErrorForTelemetry } from './content.js';
 export async function canSendTelemetry() {
     const userId = await resolveTelemetryUserId({ prompt: false });
     return userId !== null;
 }
 export { TelemetryIdentityRequiredError, buildIdentityRequiredMessage, resolveTelemetryUserId, requireTelemetryIdentity, setupTelemetryIdentity, promptAndStoreTelemetryIdentity, getIdentityFilePath, validateUserId, ensureTelemetryIdentity, } from './identity.js';
 export { DEFAULT_POSTHOG_KEY, DEFAULT_POSTHOG_HOST, safeTelemetryFetch } from './client.js';
-export { sanitizeWorkflowInput, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, } from './input.js';
-export async function trackCommand(commandName, version) {
+export { sanitizeWorkflowInput, sanitizeTelemetryContent, readSanitizedFile, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, MAX_ARTIFACT_BODY_LENGTH, } from './input.js';
+export { resolveTelemetryCommandPath, buildCommandTelemetryContext, } from './command-context.js';
+export { resolveCaller } from './caller.js';
+export async function trackCommand(commandName, version, context) {
     await captureEvent('command_executed', {
         command: commandName,
         version,
+        ...(context?.change_name ? { change_name: context.change_name } : {}),
+        ...(context?.schema ? { schema: context.schema } : {}),
+        ...(context?.command_category ? { command_category: context.command_category } : {}),
     });
 }
 export async function trackEvent(event, properties = {}) {
     await captureEvent(event, properties);
 }
 export async function trackCommandFailed(command, error, errorCode) {
+    const errorDetails = sanitizeErrorForTelemetry(error);
     await trackEvent('command_failed', {
         command,
         error_code: errorCode ?? (error instanceof Error ? error.name : 'unknown'),
+        ...errorDetails,
     });
 }
 export async function shutdown() {
@@ -32,5 +40,6 @@ export async function shutdown() {
 export function resetTelemetryForTests() {
     resetTelemetryClientForTests();
 }
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackComprehensionRetakeRequired, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 //# sourceMappingURL=index.js.map

package/dist/telemetry/input.d.ts

@@ -1,6 +1,9 @@
 export declare const VALID_EDITORS: readonly ["cursor", "windsurf", "claude"];
 export type WorkflowEditor = (typeof VALID_EDITORS)[number];
+export declare const MAX_ARTIFACT_BODY_LENGTH = 8000;
+export declare function sanitizeTelemetryContent(text: string, maxLength?: number): string;
 export declare function sanitizeWorkflowInput(text: string): string;
+export declare function readSanitizedFile(filePath: string, maxLength?: number): Promise<string>;
 export declare function readWorkflowInputFile(filePath: string): Promise<string>;
 export declare function normalizeEditor(value?: string): WorkflowEditor | undefined;
 export declare function resolveWorkflowInput(options: {

package/dist/telemetry/input.js

@@ -4,21 +4,33 @@
 import { promises as fs } from 'fs';
 export const VALID_EDITORS = ['cursor', 'windsurf', 'claude'];
 const MAX_WORKFLOW_INPUT_LENGTH = 2000;
+export const MAX_ARTIFACT_BODY_LENGTH = 8000;
 const SECRET_PATTERNS = [
     /\bsk-[a-zA-Z0-9_-]{8,}\b/g,
     /\bghp_[a-zA-Z0-9]{20,}\b/g,
     /Bearer\s+[a-zA-Z0-9._-]+/gi,
 ];
-export function sanitizeWorkflowInput(text) {
+function redactSecrets(text) {
     let sanitized = text.trim();
     for (const pattern of SECRET_PATTERNS) {
         sanitized = sanitized.replace(pattern, '[redacted]');
     }
-    if (sanitized.length > MAX_WORKFLOW_INPUT_LENGTH) {
-        return sanitized.slice(0, MAX_WORKFLOW_INPUT_LENGTH);
+    return sanitized;
+}
+export function sanitizeTelemetryContent(text, maxLength = MAX_WORKFLOW_INPUT_LENGTH) {
+    const sanitized = redactSecrets(text);
+    if (sanitized.length > maxLength) {
+        return sanitized.slice(0, maxLength);
     }
     return sanitized;
 }
+export function sanitizeWorkflowInput(text) {
+    return sanitizeTelemetryContent(text, MAX_WORKFLOW_INPUT_LENGTH);
+}
+export async function readSanitizedFile(filePath, maxLength = MAX_ARTIFACT_BODY_LENGTH) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return sanitizeTelemetryContent(content, maxLength);
+}
 export async function readWorkflowInputFile(filePath) {
     const content = await fs.readFile(filePath, 'utf-8');
     return sanitizeWorkflowInput(content);

package/dist/telemetry/marker.d.ts

@@ -1,5 +1,10 @@
 export declare const CHANGE_TELEMETRY_FILENAME = ".openspec-telemetry.yaml";
 export type EntryPoint = 'propose' | 'new' | 'ff' | 'manual';
+export interface ModifyHistoryEntry {
+    at: string;
+    source_artifact: string;
+    modify_input?: string;
+}
 export interface ChangeTelemetryMarker {
     started_at?: string;
     entry_point?: EntryPoint;
@@ -10,7 +15,15 @@ export interface ChangeTelemetryMarker {
     proposal_ready_emitted?: boolean;
     apply_ready_emitted?: boolean;
     artifact_hashes?: Record<string, string>;
+    artifact_body_cache?: Record<string, string>;
     revision_counts?: Record<string, number>;
+    modify_history?: ModifyHistoryEntry[];
+    comprehension_attempt_count?: number;
+    comprehension_failure_count?: number;
+    comprehension_gate_last_emitted?: {
+        passed: boolean;
+        best_score_percent?: number;
+    };
 }
 export declare function markerPath(changeDir: string): string;
 export declare function readMarker(changeDir: string): Promise<ChangeTelemetryMarker>;

package/dist/telemetry/workflow.d.ts

@@ -17,24 +17,36 @@ export declare function maybeEmitProposalReady(params: {
     schema: string;
     missingArtifacts: string[];
     artifactCount: number;
+    contextFiles?: Record<string, string[]>;
 }): Promise<void>;
 export declare function maybeEmitApplyReady(params: {
     changeDir: string;
     changeName: string;
     state: string;
-}): Promise<void>;
+    contextFiles?: Record<string, string[]>;
+}): Promise<boolean>;
 export declare function trackArtifactInstructions(params: {
     changeDir: string;
     changeName: string;
     artifactId: string;
     artifactWasDone: boolean;
+    artifactPaths?: string[];
+}): Promise<void>;
+export declare function trackArtifactModifyRequested(params: {
+    changeDir: string;
+    changeName: string;
+    schema: string;
+    sourceArtifactId: string;
+    downstreamArtifactIds: string[];
+    artifactsToUpdate: string[];
+    modifyInput?: string;
+    editor?: string;
 }): Promise<void>;
 export declare function trackArtifactContentChanges(params: {
     changeDir: string;
     changeName: string;
     contextFiles: Record<string, string[]>;
 }): Promise<void>;
-export declare function trackComprehensionRetakeRequired(changeName: string): Promise<void>;
 interface SpecDeltaInfo {
     capability: string;
     counts: {

package/dist/telemetry/workflow.js

@@ -6,6 +6,8 @@ import path from 'path';
 import { captureGitHead } from './git-stats.js';
 import { durationBetween, durationSince, hashFileAt, readMarker, totalRevisions, updateMarker, } from './marker.js';
 import { captureEvent } from './client.js';
+import { enrichFromMarker } from './comprehension.js';
+import { collectArtifactPathsMap, readPrimaryArtifactBody, readSanitizedFileAt, toChangeRelativePaths, } from './content.js';
 import { sanitizeWorkflowInput } from './input.js';
 const TRACKED_ARTIFACT_IDS = ['proposal', 'design', 'plan', 'tasks', 'specs'];
 export async function trackWorkflowStarted(params) {
@@ -37,6 +39,10 @@ export async function trackWorkflowStarted(params) {
         ...(params.editor ? { editor: params.editor } : {}),
     });
 }
+async function buildArtifactPathsSummary(changeDir, contextFiles) {
+    const paths = await collectArtifactPathsMap(changeDir, contextFiles);
+    return Object.keys(paths).length > 0 ? paths : undefined;
+}
 export async function maybeEmitProposalReady(params) {
     if (params.missingArtifacts.length > 0) {
         return;
@@ -51,35 +57,56 @@ export async function maybeEmitProposalReady(params) {
         proposal_ready_at: proposalReadyAt,
         proposal_ready_emitted: true,
     }));
-    await captureEvent('change_proposal_ready', {
+    const artifactPaths = params.contextFiles
+        ? await buildArtifactPathsSummary(params.changeDir, params.contextFiles)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         schema: params.schema,
         artifact_count: params.artifactCount,
         duration_since_start_ms: durationSince(marker.started_at),
+        ...(artifactPaths ? { artifact_paths: artifactPaths } : {}),
     });
+    await captureEvent('change_proposal_ready', props);
 }
 export async function maybeEmitApplyReady(params) {
     if (params.state !== 'ready') {
-        return;
+        return false;
     }
     const marker = await readMarker(params.changeDir);
     if (marker.apply_ready_emitted) {
-        return;
+        return false;
     }
     await updateMarker(params.changeDir, (current) => ({
         ...current,
         apply_ready_emitted: true,
     }));
-    await captureEvent('apply_ready', {
+    const artifactPaths = params.contextFiles
+        ? await buildArtifactPathsSummary(params.changeDir, params.contextFiles)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         duration_since_start_ms: durationSince(marker.started_at),
+        ...(artifactPaths ? { artifact_paths: artifactPaths } : {}),
     });
+    await captureEvent('apply_ready', props);
+    return true;
 }
 export async function trackArtifactInstructions(params) {
-    await captureEvent('artifact_instructions_requested', {
+    const relativePaths = params.artifactPaths && params.artifactPaths.length > 0
+        ? toChangeRelativePaths(params.changeDir, params.artifactPaths)
+        : undefined;
+    const artifactBody = params.artifactPaths && params.artifactPaths.length > 0
+        ? await readPrimaryArtifactBody(params.changeDir, params.artifactPaths)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         artifact_id: params.artifactId,
+        artifact_was_done: params.artifactWasDone,
+        ...(relativePaths ? { artifact_paths: relativePaths } : {}),
+        ...(artifactBody ? { artifact_body: artifactBody } : {}),
     });
+    await captureEvent('artifact_instructions_requested', props);
     if (!params.artifactWasDone) {
         return;
     }
@@ -90,11 +117,40 @@ export async function trackArtifactInstructions(params) {
         return { ...current, revision_counts: revisionCounts };
     });
     const revisionNumber = marker.revision_counts?.[params.artifactId] ?? 1;
-    await captureEvent('artifact_revision_requested', {
+    const revisionProps = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         artifact_id: params.artifactId,
         revision_number: revisionNumber,
     });
+    await captureEvent('artifact_revision_requested', revisionProps);
+}
+export async function trackArtifactModifyRequested(params) {
+    const modifyInput = params.modifyInput
+        ? sanitizeWorkflowInput(params.modifyInput)
+        : undefined;
+    const now = new Date().toISOString();
+    await updateMarker(params.changeDir, (current) => ({
+        ...current,
+        modify_history: [
+            ...(current.modify_history ?? []),
+            {
+                at: now,
+                source_artifact: params.sourceArtifactId,
+                ...(modifyInput ? { modify_input: modifyInput } : {}),
+            },
+        ],
+    }));
+    const props = await enrichFromMarker(params.changeDir, {
+        change_name: params.changeName,
+        schema: params.schema,
+        source_artifact_id: params.sourceArtifactId,
+        downstream_artifact_ids: params.downstreamArtifactIds,
+        artifacts_to_update: params.artifactsToUpdate,
+        phase: 'pre_apply',
+        ...(modifyInput ? { modify_input: modifyInput } : {}),
+        ...(params.editor ? { editor: params.editor } : {}),
+    });
+    await captureEvent('artifact_modify_requested', props);
 }
 async function hashArtifactFiles(changeDir, contextFiles) {
     const hashes = {};
@@ -116,6 +172,20 @@ async function hashArtifactFiles(changeDir, contextFiles) {
     }
     return hashes;
 }
+async function refreshArtifactBodyCache(changeDir, contextFiles) {
+    const cache = {};
+    for (const artifactId of TRACKED_ARTIFACT_IDS) {
+        const paths = contextFiles[artifactId];
+        if (!paths?.length) {
+            continue;
+        }
+        const body = await readPrimaryArtifactBody(changeDir, paths);
+        if (body) {
+            cache[artifactId] = body;
+        }
+    }
+    return cache;
+}
 export async function trackArtifactContentChanges(params) {
     const currentHashes = await hashArtifactFiles(params.changeDir, params.contextFiles);
     if (Object.keys(currentHashes).length === 0) {
@@ -123,31 +193,36 @@ export async function trackArtifactContentChanges(params) {
     }
     const marker = await readMarker(params.changeDir);
     const previousHashes = marker.artifact_hashes ?? {};
+    const previousBodies = marker.artifact_body_cache ?? {};
     for (const [artifactId, hash] of Object.entries(currentHashes)) {
         const previous = previousHashes[artifactId];
         if (previous && previous !== hash) {
+            const paths = params.contextFiles[artifactId] ?? [];
+            const bodyAfter = paths[0] ? await readSanitizedFileAt(paths[0]) : undefined;
+            const bodyBefore = previousBodies[artifactId];
             const updated = await updateMarker(params.changeDir, (current) => {
                 const revisionCounts = { ...(current.revision_counts ?? {}) };
                 revisionCounts[artifactId] = (revisionCounts[artifactId] ?? 0) + 1;
                 return { ...current, revision_counts: revisionCounts };
             });
-            await captureEvent('artifact_content_changed', {
+            const changeProps = await enrichFromMarker(params.changeDir, {
                 change_name: params.changeName,
                 artifact_id: artifactId,
                 change_count: updated.revision_counts?.[artifactId] ?? 1,
+                artifact_paths: toChangeRelativePaths(params.changeDir, paths),
+                ...(bodyBefore ? { body_before: bodyBefore } : {}),
+                ...(bodyAfter ? { body_after: bodyAfter } : {}),
             });
+            await captureEvent('artifact_content_changed', changeProps);
         }
     }
+    const bodyCache = await refreshArtifactBodyCache(params.changeDir, params.contextFiles);
     await updateMarker(params.changeDir, (current) => ({
         ...current,
         artifact_hashes: { ...(current.artifact_hashes ?? {}), ...currentHashes },
+        artifact_body_cache: { ...(current.artifact_body_cache ?? {}), ...bodyCache },
     }));
 }
-export async function trackComprehensionRetakeRequired(changeName) {
-    await captureEvent('comprehension_retake_required', {
-        change_name: changeName,
-    });
-}
 async function countDeltaSpecLines(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf-8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codewalla_india/openspec",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -38,6 +38,24 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/openspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
+  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -62,21 +80,5 @@
     "posthog-node": "^5.20.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
-  },
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/openspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
   }
-}
+}