@ghl-ai/aw 0.1.93 → 0.2.1

package/hooks/aw-usage/lib/aw-usage-skill-source.js

@@ -0,0 +1,229 @@
+/**
+ * AW Usage Telemetry — how a skill was reached and where its file came from (B1, B6).
+ *
+ *   skillOrigin({ name } | { path })      — 'aw' | 'other' | null (P11)
+ *   skillSourceFields(source, input, skill) — payload fields for a skill_invoked event
+ *   shellSkillReads(command)              — every SKILL.md a shell command reads
+ *   cursorProbeSkillReads(tool, toolInput) — B6 probe: a SKILL.md path given to a tool
+ *                                           this hook does not know
+ *
+ * skill_origin rule (P11):
+ * - Skill tool: `aw` for `aw:<x>`. Otherwise the skill's folder in ~/.claude/skills
+ *   (`ns:name` -> `ns-name`, else the folder whose SKILL.md declares that name),
+ *   when present, decides by the file rule below; else
+ *   `other` for any other namespace, omitted for a bare name.
+ * - File or shell read: `aw` when the SKILL.md, or the file a link to it points
+ *   to (aw links registry skills into ~/.codex/skills and ~/.cursor/skills), is
+ *   under ~/.aw-ecc/, ~/.aw/,
+ *   ~/.claude/plugins/cache/aw-marketplace/, or is a destinationPath in
+ *   ~/.cursor/ecc-install-state.json or ~/.codex/ecc-install-state.json
+ *   (those folders mix AW and other skills; the install state lists what AW
+ *   copied). Otherwise `other`. No skill list lives in the hook (spec decision 1).
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const MAX_STATE_BYTES = 2 * 1024 * 1024;
+const INSTALL_STATE_FILES = [['.cursor', 'ecc-install-state.json'], ['.codex', 'ecc-install-state.json']];
+const AW_ROOTS = [['.aw-ecc'], ['.aw'], ['.claude', 'plugins', 'cache', 'aw-marketplace']];
+// B6 probe skips tools whose skill reads are already counted, and search tools:
+// Cursor Greps for `**/<name>/SKILL.md` before reading it, which is not a load.
+const PROBE_SKIPPED_TOOLS = new Set(['Read', 'Bash', 'Shell', 'Skill', 'Grep', 'Glob']);
+const SKILL_FILE = /(?<=^|[\s'"`;|&<>()=])((?:[^\s'"`;|&<>()]*\/)?skills\/([A-Za-z0-9._:-]+)\/SKILL\.md)(?![\w.-])/g;
+
+const listedCache = new Map();
+
+function toForwardSlashes(value) {
+  return String(value).replace(/\\/g, '/');
+}
+
+function expandHome(filePath, home) {
+  const match = filePath.match(/^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/);
+  return match ? path.join(home, filePath.slice(match[0].length)) : filePath;
+}
+
+function readInstallState(statePath) {
+  try {
+    if (fs.statSync(statePath).size > MAX_STATE_BYTES) return [];
+    const operations = JSON.parse(fs.readFileSync(statePath, 'utf8'))?.operations;
+    return Array.isArray(operations) ? operations.map(op => op?.destinationPath).filter(p => typeof p === 'string') : [];
+  } catch {
+    // Missing, too big or not JSON: nothing is listed, so the skill counts as `other`.
+    return [];
+  }
+}
+
+// Install-state files are read once per process.
+function listedSkillPaths(home) {
+  if (!listedCache.has(home)) {
+    const listed = new Set();
+    for (const segments of INSTALL_STATE_FILES) {
+      for (const destination of readInstallState(path.join(home, ...segments))) {
+        if (/\/SKILL\.md$/i.test(toForwardSlashes(destination))) listed.add(toForwardSlashes(path.normalize(destination)));
+      }
+    }
+    listedCache.set(home, listed);
+  }
+  return listedCache.get(home);
+}
+
+// Read-only: resolves links, never creates, moves or deletes anything. The OS
+// resolver (.native) applies `..` after following links; the JS one collapses
+// `..` first, so `~/.aw/link/../x` would wrongly stay under ~/.aw.
+function realPath(filePath) {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    // Broken link, loop, unreadable folder or missing file.
+    return null;
+  }
+}
+
+function isUnderAwRoot(filePath, homes) {
+  const file = toForwardSlashes(filePath);
+  return homes.some(home => AW_ROOTS.some(segments => file.startsWith(`${toForwardSlashes(path.join(home, ...segments))}/`)));
+}
+
+// The real file decides: aw links registry skills into ~/.codex/skills,
+// ~/.cursor/skills and ~/.claude/skills, pointing into ~/.aw. A path that cannot
+// be resolved (missing, broken link) is judged as given.
+// Known limit: an AW folder that is itself a link (e.g. ~/.aw-ecc -> a dev
+// checkout) is not followed, so its skills count as other. `aw init` clones into
+// the real folders.
+function originFromPath(filePath, home) {
+  const given = expandHome(filePath, home);
+  const absolute = path.normalize(given);
+  if (listedSkillPaths(home).has(toForwardSlashes(absolute))) return 'aw';
+  const real = realPath(given);
+  if (!real) return isUnderAwRoot(absolute, [home]) ? 'aw' : 'other';
+  return isUnderAwRoot(real, [home, realPath(home) || home]) ? 'aw' : 'other';
+}
+
+function originFromName(name) {
+  const colon = String(name).indexOf(':');
+  if (colon <= 0) return null;
+  return name.slice(0, colon).toLowerCase() === 'aw' ? 'aw' : 'other';
+}
+
+// A Skill-tool name as one folder name: `platform-core:echo-direct` -> `platform-core-echo-direct`.
+const SKILL_NAME = /^[A-Za-z0-9._-]+(?::[A-Za-z0-9._-]+)?$/;
+
+// Claude's Skill tool gives only a name. Its folder in ~/.claude/skills (often a
+// link aw made into ~/.aw/.aw_registry) is where the skill came from.
+const SKILL_HEAD_BYTES = 2048;
+const namedCache = new Map();
+
+function frontmatterName(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(SKILL_HEAD_BYTES);
+    const head = buf.toString('utf8', 0, fs.readSync(fd, buf, 0, SKILL_HEAD_BYTES, 0)).replace(/^\uFEFF/, '');
+    // Only the front matter (between the opening and closing ---) names the skill.
+    const frontMatter = head.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    const match = frontMatter && frontMatter[1].match(/^name:[ \t]*["']?([^"'\r\n]+?)["']?[ \t]*$/m);
+    return match ? match[1] : null;
+  } catch {
+    // Unreadable or broken link: it cannot be the skill Claude loaded.
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// name -> SKILL.md for skills whose folder name differs from their `name:`
+// (e.g. platform-core-architecture-design declares platform-shared:architecture-design).
+// Read once per process.
+function skillsByName(dir) {
+  if (!namedCache.has(dir)) {
+    const byName = new Map();
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch { /* no skills folder: nothing to match */ }
+    for (const entry of entries) {
+      const file = path.join(dir, entry, 'SKILL.md');
+      const name = frontmatterName(file);
+      if (name && !byName.has(name)) byName.set(name, file);
+    }
+    namedCache.set(dir, byName);
+  }
+  return namedCache.get(dir);
+}
+
+function claudeSkillFile(name, home) {
+  if (!SKILL_NAME.test(name) || name.split(':').some(part => /^\.+$/.test(part))) return null;
+  const dir = path.join(home, '.claude', 'skills');
+  const file = path.join(dir, name.replace(':', '-'), 'SKILL.md');
+  if (fs.existsSync(file)) return file;
+  return skillsByName(dir).get(name) || null;
+}
+
+/** @param {{ name?: string, path?: string }} skill */
+function skillOrigin(skill, { home: givenHome = os.homedir() } = {}) {
+  // One spelling of HOME (no trailing slash) for prefix checks and caches.
+  const home = path.resolve(givenHome);
+  if (typeof skill?.path === 'string' && skill.path) return originFromPath(skill.path, home);
+  if (typeof skill?.name === 'string' && skill.name) {
+    const byName = originFromName(skill.name);
+    if (byName === 'aw') return byName;
+    const file = claudeSkillFile(skill.name, home);
+    return file ? originFromPath(file, home) : byName;
+  }
+  return null;
+}
+
+/**
+ * @param {'skill_tool'|'file_read'|'shell_read'|'other_tool'} source
+ * @param {object} input hook input
+ * @param {{ name?: string, path?: string }} skill
+ */
+function skillSourceFields(source, input, skill, opts = {}) {
+  const origin = skillOrigin(skill, opts);
+  return {
+    source,
+    tool_name: input?.tool_name || 'unknown',
+    ...(typeof input?.tool_use_id === 'string' && input.tool_use_id ? { tool_use_id: input.tool_use_id } : {}),
+    ...(origin ? { skill_origin: origin } : {}),
+  };
+}
+
+/** Every distinct skill whose SKILL.md appears in the text, first-seen order. */
+function shellSkillReads(text) {
+  const reads = [];
+  const seen = new Set();
+  for (const match of toForwardSlashes(text || '').matchAll(SKILL_FILE)) {
+    if (seen.has(match[2])) continue;
+    seen.add(match[2]);
+    reads.push({ name: match[2], path: match[1] });
+  }
+  return reads;
+}
+
+function shellSkillNames(command) {
+  return shellSkillReads(command).map(read => read.name);
+}
+
+function stringsToDepth(value, depth) {
+  if (typeof value === 'string') return [value];
+  if (depth === 0 || !value || typeof value !== 'object') return [];
+  return Object.values(value).flatMap(child => stringsToDepth(child, depth - 1));
+}
+
+// B6 probe: remove in the release after the one that ships it
+// (https://app.clickup.com/t/14zhcp5e0b5).
+function cursorProbeSkillReads(toolName, toolInput) {
+  if (!toolName || PROBE_SKIPPED_TOOLS.has(toolName)) return [];
+  return shellSkillReads(stringsToDepth(toolInput, 2).join('\n'));
+}
+
+module.exports = {
+  AW_ROOTS,
+  skillOrigin,
+  skillSourceFields,
+  shellSkillReads,
+  shellSkillNames,
+  cursorProbeSkillReads,
+};

package/hooks/aw-usage/lib/aw-usage-stage-events.js

@@ -0,0 +1,179 @@
+/**
+ * AW Usage Telemetry — loop-aware stage events (B4).
+ *
+ *   isCompletionStatus(status)               — P13 text rule for a finished stage
+ *   decideStageEvents(history, { stage, status, now }) — pure: events + new history
+ *   processStateJsonWrite({ filePath, … })   — read the written state.json, update the
+ *                                              laptop history, return the events to send
+ *
+ * A write to .aw_docs/features/<slug>/state.json is a start when its `stage`
+ * is new or changed (or the same stage again after it was completed), and a
+ * completion when its `status` reads as finished. History lives on the laptop
+ * in ~/.aw/telemetry/stages/<project_hash>/<slug>.json (P12): the hook never
+ * writes into the repo. When the stage skills write a fixed status and a
+ * stage history into state.json (https://app.clickup.com/t/14zhcp5e0bh), only
+ * the input of decideStageEvents changes.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { withFileLock, sessionFileName } = require('./aw-usage-envelope');
+const { commandKey } = require('./aw-usage-commands');
+
+const STAGES_DIR = path.join(os.homedir(), '.aw', 'telemetry', 'stages');
+// `investigate` is a valid stage outside the plan → ship order.
+const KNOWN_STAGES = new Set(['plan', 'build', 'test', 'verify', 'review', 'deploy', 'ship', 'investigate']);
+const STAGE_FOR_COMMAND = {
+  plan: 'plan', build: 'build', execute: 'build', test: 'test', verify: 'verify',
+  review: 'review', deploy: 'deploy', ship: 'ship', investigate: 'investigate',
+};
+const STATE_JSON = /(?:^|\/)\.aw_docs\/features\/([^/]+)\/state\.json$/;
+const MAX_STATE_BYTES = 1024 * 1024;
+const MAX_STATUS_RAW = 60;
+const MAX_PATTERN_ID = 100;
+const COMPLETED = /(?:^|_)(?:complete|completed|done|passed|pass)(?:_|$)/;
+const NOT_COMPLETED = /(?:^|_)(?:blocked|failed|fail)(?:_|$)/;
+
+// `stage`: the stage the write is in. `ready_for_<stage>` for that same stage
+// means it has not started yet, so it is not a completion.
+function isCompletionStatus(status, stage = null) {
+  if (typeof status !== 'string' || !status) return false;
+  const value = status.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+  if (NOT_COMPLETED.test(value)) return false;
+  if (value.startsWith('ready_for_')) return !stage || value !== `ready_for_${stage}`;
+  return COMPLETED.test(value);
+}
+
+function decideStageEvents(history, { stage, status, now }) {
+  if (!KNOWN_STAGES.has(stage)) return { events: [], history };
+  const entries = Array.isArray(history?.entries) ? [...history.entries] : [];
+  const events = [];
+  const completion = isCompletionStatus(status, stage);
+  const current = entries[entries.length - 1];
+
+  const isNewStage = !current || current.stage !== stage;
+  if (isNewStage || (current.completed && !completion)) {
+    const loopIndex = entries.filter(entry => entry.stage === stage).length;
+    events.push({ type: 'started', stage, from_stage: current ? current.stage : null, loop_index: loopIndex });
+    entries.push({ stage, loop_index: loopIndex, started_at: now, completed: false });
+  }
+
+  const open = entries[entries.length - 1];
+  if (completion && open.stage === stage && !open.completed) {
+    events.push({ type: 'completed', stage, loop_index: open.loop_index });
+    entries[entries.length - 1] = { ...open, completed: true };
+  }
+  return { events, history: { entries } };
+}
+
+/** 'user' when the last prompt typed the command for this stage, else 'agent'. */
+function stageStartedBy(stage, lastPromptCommands) {
+  const typed = Array.isArray(lastPromptCommands) ? lastPromptCommands : [];
+  return typed.some(command => STAGE_FOR_COMMAND[commandKey(command?.raw_name)] === stage) ? 'user' : 'agent';
+}
+
+function readStateJson(absolutePath) {
+  try {
+    if (fs.statSync(absolutePath).size > MAX_STATE_BYTES) return null;
+    const state = JSON.parse(fs.readFileSync(absolutePath, 'utf8'));
+    return state && typeof state === 'object' && !Array.isArray(state) ? state : null;
+  } catch {
+    // Unreadable or not JSON: no stage event for this write.
+    return null;
+  }
+}
+
+function readHistory(historyPath) {
+  try {
+    return JSON.parse(fs.readFileSync(historyPath, 'utf8'));
+  } catch {
+    // First write for this feature on this laptop.
+    return { entries: [] };
+  }
+}
+
+// tmp file + rename: a crash mid-write never leaves half a history behind.
+function writeHistory(historyPath, history) {
+  const tmpPath = `${historyPath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(history), { mode: 0o600 });
+  fs.renameSync(tmpPath, historyPath);
+}
+
+function toEvent(decision, { slug, relativePath, state, startedBy }) {
+  if (decision.type === 'started') {
+    const patternId = typeof state.pattern_id === 'string' && state.pattern_id.length <= MAX_PATTERN_ID ? state.pattern_id : null;
+    return {
+      eventType: 'sdlc_stage_started',
+      payload: {
+        feature_slug: slug,
+        stage: decision.stage,
+        from_stage: decision.from_stage,
+        loop_index: decision.loop_index,
+        started_by: startedBy,
+        ...(patternId ? { pattern_id: patternId } : {}),
+        file_path: relativePath,
+      },
+    };
+  }
+  return {
+    eventType: 'sdlc_stage_completed',
+    payload: {
+      feature_slug: slug,
+      stage: decision.stage,
+      loop_index: decision.loop_index,
+      status_raw: String(state.status).slice(0, MAX_STATUS_RAW),
+      file_path: relativePath,
+    },
+  };
+}
+
+/**
+ * @param {{ filePath: string, projectRoot: string, projectHash: string|null,
+ *   lastPromptCommands?: Array<{ raw_name: string }>, stagesDir?: string, now?: () => string }} opts
+ * @returns {Array<{ eventType: string, payload: object }>}
+ */
+function processStateJsonWrite({ filePath, projectRoot, projectHash, lastPromptCommands = [], stagesDir = STAGES_DIR, now = () => new Date().toISOString() }) {
+  const norm = String(filePath || '').replace(/\\/g, '/');
+  if (!projectHash || !projectRoot) return [];
+  const root = path.posix.normalize(String(projectRoot).replace(/\\/g, '/')).replace(/\/+$/, '');
+  const isAbsolute = norm.startsWith('/') || /^[A-Za-z]:\//.test(norm);
+  // Resolve `..` before the check, so a path cannot step out of the project.
+  const absolutePath = path.posix.normalize(isAbsolute ? norm : `${root}/${norm}`);
+  // Only the project's own feature folders are read.
+  if (!root || !absolutePath.startsWith(`${root}/`)) return [];
+  const relativePath = absolutePath.slice(root.length + 1);
+  const match = relativePath.match(STATE_JSON);
+  if (!match) return [];
+
+  const state = readStateJson(absolutePath);
+  const stage = typeof state?.stage === 'string' ? state.stage.trim().toLowerCase() : null;
+  if (!state || !KNOWN_STAGES.has(stage)) return [];
+
+  const slug = match[1];
+  const featureDir = path.join(stagesDir, sessionFileName(projectHash));
+  const historyPath = path.join(featureDir, `${sessionFileName(slug)}.json`);
+  try {
+    fs.mkdirSync(featureDir, { recursive: true, mode: 0o700 });
+    const result = withFileLock(`${historyPath}.lock`, () => {
+      const decision = decideStageEvents(readHistory(historyPath), { stage, status: state.status, now: now() });
+      if (decision.events.length > 0) writeHistory(historyPath, decision.history);
+      return decision.events;
+    }, { waitMs: 200 });
+    if (!result.ok) return [];
+    const startedBy = stageStartedBy(stage, lastPromptCommands);
+    return result.value.map(decision => toEvent(decision, { slug, relativePath, state, startedBy }));
+  } catch {
+    // Telemetry folder not writable: no stage event, the rest of the hook is unaffected.
+    return [];
+  }
+}
+
+module.exports = {
+  isCompletionStatus,
+  decideStageEvents,
+  stageStartedBy,
+  processStateJsonWrite,
+};