@aiwg/cli 2026.7.19 → 2026.7.21

package/dist/src/cli/handlers/utilities.js

@@ -14,7 +14,7 @@ import fsp from 'fs/promises';
 import path from 'path';
 import { createScriptRunner } from './script-runner.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
-import { forceUpdateCheck } from '../../update/checker.mjs';
+import { updateInstallation } from '../../update/service.mjs';
 import { useHandler as useFrameworkHandler } from './use.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { checkCollisions, } from '../../smiths/skillsmith/collision-detector.js';
@@ -130,8 +130,8 @@ function countSentences(s) {
     return matches.length + (endsWithTerminator ? 0 : 1);
 }
 /**
- * Scan source SKILL.md files in `agentic/code/` for namespace issues:
- * - Missing `namespace: aiwg`
+ * Scan canonical AIWG source SKILL.md files in `agentic/code/` for policy issues:
+ * - Missing the AIWG-only `namespace: aiwg` source convention
  * - Slug (`aiwg-{name}`) that would shadow an AIWG CLI command
  *
  * Returns lines suitable for console output, or empty array if clean.
@@ -263,12 +263,14 @@ export const validateMetadataHandler = {
         const result = await runner.run('tools/cli/validate-metadata.mjs', scriptArgs, {
             cwd: ctx.cwd,
         });
-        // Append namespace validation: scan source SKILL.md files
+        // Append canonical AIWG source policy. `namespace` is an AIWG extension,
+        // not an Agent Skills standard requirement; shared conformance is emitted
+        // by validate-metadata.mjs before this source-only convention.
         try {
             const issues = await scanSourceNamespaceIssues(frameworkRoot);
             if (issues.length > 0) {
-                console.log('\n── Namespace validation ──');
-                console.log(`  ${issues.length} skill(s) missing namespace field:`);
+                console.log('\n── AIWG source conventions ──');
+                console.log(`  ${issues.length} canonical source convention issue(s):`);
                 // Show first 20 to avoid flooding output
                 issues.slice(0, 20).forEach(l => console.log(l));
                 if (issues.length > 20) {
@@ -276,11 +278,11 @@ export const validateMetadataHandler = {
                 }
                 // Non-zero exit only in strict mode
                 if (ctx.args.includes('--strict') && result.exitCode === 0) {
-                    return { exitCode: 1, message: `Namespace validation failed: ${issues.length} skill(s) missing namespace field` };
+                    return { exitCode: 1, message: `AIWG source convention validation failed: ${issues.length} issue(s)` };
                 }
             }
             else {
-                console.log('\n── Namespace validation: all skills have namespace field ✓');
+                console.log('\n── AIWG source conventions: all canonical skills include the AIWG namespace extension ✓');
             }
         }
         catch {
@@ -460,6 +462,16 @@ export const doctorHandler = {
         const runner = createScriptRunner(frameworkRoot);
         // Run core doctor diagnostics
         const result = await runner.run('tools/cli/doctor.mjs', ctx.args, { cwd: ctx.cwd });
+        let agentSkillsFailure = false;
+        try {
+            const { buildAgentSkillsDoctorSection } = await import('../../skills/doctor.js');
+            const section = buildAgentSkillsDoctorSection(ctx.cwd || process.cwd());
+            console.log(section.output);
+            agentSkillsFailure = section.hasFailures;
+        }
+        catch (error) {
+            console.log(`\n── Agent Skills conformance ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
+        }
         // Surface feedback escape hatch when doctor finds issues
         if (result.exitCode !== 0) {
             console.log(`
@@ -536,6 +548,21 @@ export const doctorHandler = {
         catch {
             // Project-local section is non-fatal for doctor
         }
+        // Web-backed resource lock/cache diagnostics (#1850). Report lock source
+        // mode, cold cache, and digest drift without requiring web mode to be in use.
+        try {
+            const { buildWebResourceDoctorSection } = await import('../../resources/doctor.js');
+            const section = buildWebResourceDoctorSection(ctx.cwd || process.cwd(), {
+                cacheRoot: process.env.AIWG_RESOURCE_CACHE_ROOT,
+            });
+            if (section.output)
+                console.log(section.output);
+            if (section.hasFailures)
+                return { exitCode: 1, message: '' };
+        }
+        catch (error) {
+            console.log(`\n── Web resource cache ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
+        }
         // Canonical workspace-context graph diagnostics (#1811). Legacy projects
         // remain valid; drift, loops, conflicts, and possible credentials fail.
         try {
@@ -552,7 +579,9 @@ export const doctorHandler = {
         catch (error) {
             console.log(`\n── Workspace context graph ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
         }
-        return result;
+        return agentSkillsFailure
+            ? { exitCode: 1, message: '' }
+            : result;
     },
 };
 /**
@@ -578,7 +607,7 @@ export const updateHandler = {
     name: 'Update',
     description: 'Update AIWG and re-deploy installed frameworks',
     category: 'maintenance',
-    aliases: ['-update', '--update'],
+    aliases: ['-update', '--update', 'upgrade'],
     async execute(ctx) {
         const args = ctx.args;
         const deployAll = args.includes('--all');
@@ -592,8 +621,12 @@ export const updateHandler = {
         // Step 1: Check for package updates (unless --skip-check)
         if (!skipCheck) {
             try {
-                console.log('Checking for AIWG updates...\n');
-                await forceUpdateCheck();
+                console.log('Updating AIWG installation...\n');
+                const update = await updateInstallation({
+                    dryRun,
+                    offline: args.includes('--offline'),
+                });
+                console.log(`${update.message}\n`);
             }
             catch (error) {
                 console.error(`Warning: Update check failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -626,30 +659,12 @@ export const updateHandler = {
             console.log('  aiwg use all');
             return { exitCode: 0 };
         }
-        // Map registry IDs to framework use-names
-        const installedFrameworks = [];
-        const unmapped = [];
-        for (const fw of registry.frameworks) {
-            const useName = REGISTRY_ID_TO_USE_NAME[fw.id];
-            if (useName) {
-                installedFrameworks.push(useName);
-            }
-            else {
-                unmapped.push(fw.id);
-            }
-        }
-        if (installedFrameworks.length === 0) {
-            console.log('No recognized frameworks in registry');
-            if (unmapped.length > 0) {
-                console.log(`Unrecognized entries: ${unmapped.join(', ')}`);
-            }
-            return { exitCode: 0 };
-        }
+        // Canonical framework IDs need their historical public aliases. Add-ons,
+        // extensions, and project-local bundles are already accepted by `aiwg use`,
+        // so preserve their registry IDs instead of silently skipping them.
+        const installedFrameworks = registry.frameworks.map(item => REGISTRY_ID_TO_USE_NAME[item.id] ?? item.id);
         // Report what will be updated
         console.log(`Installed frameworks: ${installedFrameworks.join(', ')}`);
-        if (unmapped.length > 0) {
-            console.log(`Skipping unrecognized: ${unmapped.join(', ')}`);
-        }
         console.log('');
         if (dryRun) {
             console.log('Dry run: Would re-deploy the following frameworks:');

package/dist/src/cli/skill-usage.js

@@ -1,12 +1,16 @@
 import { mkdir, readFile, rename, stat, writeFile, appendFile, readdir } from 'fs/promises';
-import { existsSync } from 'fs';
+import { createReadStream, existsSync } from 'fs';
 import { createHash } from 'crypto';
+import { createInterface } from 'readline';
 import path from 'path';
 import os from 'os';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
 const DEFAULT_REPORT_LIMIT = 20;
+const MAX_TRANSCRIPT_LINE_BYTES = 1_048_576;
+const MAX_TRANSCRIPT_BYTES = 256 * 1_048_576;
+const MAX_TRANSCRIPT_RECORDS = 1_000_000;
 export async function maybeAppendSkillUsage(input) {
     const env = input.env ?? process.env;
     const resolved = await resolveSkillUsageSettings(input.cwd, env);
@@ -43,15 +47,38 @@ export async function ingestSkillUsageTranscript(options) {
     const contextCwd = options.projectRoot ?? options.cwd;
     const resolved = await resolveSkillUsageSettings(contextCwd, env);
     if (!resolved.enabled || resolved.scopes.length === 0) {
-        return { events: [], appended: 0, skipped: 0, paths: [] };
+        return {
+            events: [], appended: 0, skipped: 0, paths: [],
+            receipt: {
+                source_generation: '', provider: normalizeProvider(options.provider),
+                records_read: 0, events_extracted: 0, events_appended: 0,
+                duplicates_skipped: 0, malformed_skipped: 0,
+            },
+        };
+    }
+    const provider = normalizeProvider(options.provider);
+    if (provider !== 'claude-code') {
+        throw new Error(`unsupported skill-usage transcript provider: ${provider}`);
     }
-    const raw = await readFile(options.transcriptPath, 'utf8');
-    const lines = raw.split('\n').map(line => line.trim()).filter(Boolean);
+    const sourceStat = await stat(options.transcriptPath);
+    const sourceGeneration = digest([
+        provider, String(sourceStat.size), String(sourceStat.mtimeMs),
+    ].join('\0'));
     const version = await readAiwgVersion(options.frameworkRoot);
     const context = await resolvePathContext(contextCwd);
     const extracted = [];
     let skipped = 0;
-    for (const line of lines) {
+    let recordsRead = 0;
+    let bytesRead = 0;
+    for await (const line of streamTranscriptLines(options.transcriptPath)) {
+        recordsRead += 1;
+        bytesRead += Buffer.byteLength(line) + 1;
+        if (recordsRead > MAX_TRANSCRIPT_RECORDS || bytesRead > MAX_TRANSCRIPT_BYTES) {
+            throw new Error('skill-usage transcript exceeds bounded ingestion limits');
+        }
+        if (Buffer.byteLength(line) > MAX_TRANSCRIPT_LINE_BYTES) {
+            throw new Error('skill-usage transcript record exceeds bounded line limit');
+        }
         let parsed;
         try {
             parsed = JSON.parse(line);
@@ -65,22 +92,50 @@ export async function ingestSkillUsageTranscript(options) {
             skipped += 1;
         }
         else {
-            extracted.push(...events);
+            extracted.push(...events.map(event => ({
+                ...event,
+                occurredAt: sourceOccurrenceTime(parsed),
+                nativeEventId: sourceNativeEventId(parsed),
+                position: recordsRead,
+                contentDigest: digest(line),
+            })));
         }
     }
     const persisted = [];
     const paths = resolved.scopes
         .map(scope => resolveUsagePath(scope, context.projectRoot, env))
         .filter((p) => Boolean(p));
+    const knownEventIdsByPath = new Map();
+    for (const filePath of paths) {
+        const knownEventIds = new Set();
+        for (const event of await readJsonlEvents(filePath)) {
+            if (event.event_id)
+                knownEventIds.add(event.event_id);
+        }
+        knownEventIdsByPath.set(filePath, knownEventIds);
+    }
+    let duplicatesSkipped = 0;
     for (const scope of resolved.scopes) {
         const filePath = resolveUsagePath(scope, context.projectRoot, env);
         if (!filePath)
             continue;
+        const knownEventIds = knownEventIdsByPath.get(filePath) ?? new Set();
         for (const item of extracted) {
+            const eventId = digest([
+                sourceGeneration,
+                item.nativeEventId ?? String(item.position),
+                item.contentDigest,
+                item.artifact.kind,
+                item.artifact.id,
+            ].join('\0'));
+            if (knownEventIds.has(eventId)) {
+                duplicatesSkipped += 1;
+                continue;
+            }
             const event = buildUsageEvent({
                 env,
                 source: 'transcript',
-                provider: normalizeProvider(options.provider),
+                provider,
                 artifact: item.artifact,
                 action: item.action,
                 outcome: 'unknown',
@@ -88,8 +143,13 @@ export async function ingestSkillUsageTranscript(options) {
                 cwd: context.projectRoot ?? contextCwd,
                 context,
                 scope,
+                occurredAt: item.occurredAt,
+                eventId,
+                sourceGeneration,
+                nativeEventId: item.nativeEventId,
             });
             persisted.push(event);
+            knownEventIds.add(eventId);
             if (!options.dryRun) {
                 await appendBoundedJsonl(filePath, event, resolved.maxBytes);
             }
@@ -100,6 +160,15 @@ export async function ingestSkillUsageTranscript(options) {
         appended: options.dryRun ? 0 : persisted.length,
         skipped,
         paths,
+        receipt: {
+            source_generation: sourceGeneration,
+            provider,
+            records_read: recordsRead,
+            events_extracted: extracted.length,
+            events_appended: options.dryRun ? 0 : persisted.length,
+            duplicates_skipped: duplicatesSkipped,
+            malformed_skipped: skipped,
+        },
     };
 }
 export async function readSkillUsageReport(options) {
@@ -131,6 +200,10 @@ export async function readSkillUsageReport(options) {
             limit: 5,
         }),
         paths,
+        window: {
+            retained_segments: paths.reduce((count, filePath) => count + retainedUsagePaths(filePath).filter(existsSync).length, 0),
+            truncated_before: paths.some(filePath => existsSync(`${filePath}.1`)),
+        },
     };
 }
 export async function printSkillUsageReport(options) {
@@ -205,10 +278,17 @@ function classifyCliUsage(command, args) {
     return { kind: 'command', id: command, action: 'invoke' };
 }
 function buildUsageEvent(input) {
+    const observedTimestamp = new Date().toISOString();
     const event = {
-        schema_version: 1,
+        schema_version: input.eventId ? 2 : 1,
         event_type: 'aiwg.skill_usage',
-        timestamp: new Date().toISOString(),
+        timestamp: input.occurredAt ?? observedTimestamp,
+        ...(input.eventId ? {
+            observed_timestamp: observedTimestamp,
+            event_id: input.eventId,
+            source_generation: input.sourceGeneration,
+            native_event_id: input.nativeEventId,
+        } : {}),
         invocation_id: input.env.AIWG_INVOCATION_ID,
         source: input.source,
         provider: input.provider,
@@ -294,6 +374,25 @@ function normalizeProvider(value) {
         return 'claude-code';
     return normalized || 'unknown';
 }
+function sourceOccurrenceTime(value) {
+    if (!isRecord(value))
+        return undefined;
+    for (const key of ['timestamp', 'created_at', 'createdAt', 'time']) {
+        const candidate = value[key];
+        if (typeof candidate === 'string' && !Number.isNaN(Date.parse(candidate))) {
+            return new Date(candidate).toISOString();
+        }
+    }
+    return undefined;
+}
+function sourceNativeEventId(value) {
+    if (!isRecord(value))
+        return undefined;
+    return firstString(value, ['uuid', 'event_id', 'eventId', 'id', 'message_id']);
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
 function isArtifactKind(value) {
     return value === 'skill' ||
         value === 'agent' ||
@@ -393,15 +492,20 @@ function resolveUsagePath(scope, projectRoot, env) {
 }
 async function appendBoundedJsonl(filePath, event, maxBytes) {
     await mkdir(path.dirname(filePath), { recursive: true });
-    await rotateIfNeeded(filePath, maxBytes);
-    await appendFile(filePath, JSON.stringify(event) + '\n', 'utf8');
-}
-async function rotateIfNeeded(filePath, maxBytes) {
+    const line = JSON.stringify(event) + '\n';
+    const lineBytes = Buffer.byteLength(line);
+    if (maxBytes > 0 && lineBytes > maxBytes)
+        event.oversized_record = true;
+    const finalLine = JSON.stringify(event) + '\n';
+    await rotateIfNeeded(filePath, maxBytes, Buffer.byteLength(finalLine));
+    await appendFile(filePath, finalLine, 'utf8');
+}
+async function rotateIfNeeded(filePath, maxBytes, appendBytes) {
     if (maxBytes <= 0)
         return;
     try {
         const current = await stat(filePath);
-        if (current.size <= maxBytes)
+        if (current.size === 0 || current.size + appendBytes <= maxBytes)
             return;
         const rotated = `${filePath}.1`;
         if (existsSync(rotated)) {
@@ -415,18 +519,36 @@ async function rotateIfNeeded(filePath, maxBytes) {
     }
 }
 async function readJsonlEvents(filePath) {
+    const events = [];
+    for (const retainedPath of retainedUsagePaths(filePath)) {
+        try {
+            for await (const line of streamTranscriptLines(retainedPath)) {
+                if (line.trim())
+                    events.push(JSON.parse(line));
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return events;
+}
+function retainedUsagePaths(filePath) {
+    return [`${filePath}.1`, filePath];
+}
+async function* streamTranscriptLines(filePath) {
+    const input = createReadStream(filePath, { encoding: 'utf8' });
+    const lines = createInterface({ input, crlfDelay: Infinity });
     try {
-        const raw = await readFile(filePath, 'utf8');
-        return raw
-            .split('\n')
-            .map(line => line.trim())
-            .filter(Boolean)
-            .map(line => JSON.parse(line));
+        for await (const line of lines) {
+            if (line.trim())
+                yield line;
+        }
     }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
+    finally {
+        lines.close();
+        input.destroy();
     }
 }
 function summarizeEvents(events) {

package/dist/src/config/cli.js

@@ -21,6 +21,7 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import { UserConfig } from './user-config.js';
 import { AiwgError, EXIT_CODES } from '../cli/errors.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from './project-artifacts.js';
 const _scriptDir = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Main CLI entry point for `aiwg config <subcommand> [args]`
@@ -182,7 +183,7 @@ async function projectConfigGet(key, args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to set up repo/tracker/delivery policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -362,7 +363,7 @@ async function handleProjectValidate(args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then configure project policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -403,7 +404,8 @@ async function handleProjectValidate(args) {
             ? validateIssueLabels(cfg.issues)
             : resolveIssueLabels(undefined, 'local').diagnostics;
     const diagnostics = [...indexErrors, ...externalLinkErrors, ...labelDiagnostics];
-    console.log(`Project config: ${projectDir}/.aiwg/aiwg.config\n`);
+    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     if (diagnostics.length === 0) {
         console.log('✓ Project config valid');
         return;
@@ -464,7 +466,7 @@ async function projectConfigReset(key, args) {
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to establish project policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -553,7 +555,7 @@ For project-level config: aiwg config show --project [--json]
     if (!cfg) {
         throw new AiwgError({
             code: 'ERR_NO_PROJECT_CONFIG',
-            message: 'No .aiwg/aiwg.config in this project.',
+            message: 'No project AIWG config found at the resolved artifact root.',
             hint: 'Run `aiwg init`, then ask your AIWG agent to set up repo/tracker/delivery policy.',
             exitCode: EXIT_CODES.CONFIG,
         });
@@ -593,7 +595,8 @@ For project-level config: aiwg config show --project [--json]
         return;
     }
     // Human-readable view
-    console.log(`Project config: ${projectDir}/.aiwg/aiwg.config\n`);
+    console.log(`Project config: ${projectAiwgPath(projectDir, 'aiwg.config')}`);
+    console.log(`Artifact root:  ${resolveProjectAiwgDir(projectDir)}\n`);
     console.log(`Schema version: ${cfg.version}`);
     console.log(`Providers:      ${cfg.providers.join(', ') || '(none)'}`);
     console.log('');
@@ -663,13 +666,14 @@ function printUsage() {
 
 Subcommands:
   get <key>                       Read a user config value
-  get --project <key>             Read a project config value (.aiwg/aiwg.config)
+  get --project <key>             Read a project config value (default .aiwg/aiwg.config;
+                                  AIWG_ARTIFACTS_PATH may override the artifact root)
   set <key> <value>               Write a user config value
   set --project <key> <value>     Write a project config value (validates enums)
   list                Show all user config
-  show --project      Show resolved project config (.aiwg/aiwg.config)
+  show --project      Show resolved project config and artifact root
   validate            Validate user config files
-  validate --project  Validate .aiwg/aiwg.config taxonomy/index semantics
+  validate --project  Validate resolved project config taxonomy/index semantics
     [--provider gitea|github|local] [--available-label NAME ...]
   reset [<key>]       Reset key or all config to defaults
   path                Print config directory path

package/dist/src/config/project-artifacts-runtime.mjs

@@ -0,0 +1,68 @@
+/**
+ * Runtime implementation of project AIWG artifact directory resolution.
+ *
+ * Kept as ESM JavaScript so direct `.mjs` tools and compiled TypeScript
+ * consumers share exactly one resolver implementation.
+ */
+
+import { homedir } from 'os';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, join, resolve } from 'path';
+
+export const DEFAULT_PROJECT_AIWG_DIR = '.aiwg';
+export const AIWG_ARTIFACTS_PATH_ENV = 'AIWG_ARTIFACTS_PATH';
+export const PROJECT_AIWG_LOCATION_FILE = '.aiwg-location';
+
+const ARTIFACT_PATH_ENV_ALIASES = [
+  AIWG_ARTIFACTS_PATH_ENV,
+  'AIWG_PROJECT_ARTIFACTS_PATH',
+  'AIWG_PROJECT_AIWG_DIR',
+];
+
+export function expandProjectArtifactPath(pathValue, projectDir) {
+  const trimmed = pathValue.trim();
+  if (trimmed === '~') return homedir();
+  if (trimmed.startsWith('~/')) return resolve(homedir(), trimmed.slice(2));
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(projectDir, trimmed);
+}
+
+export function parseProjectArtifactLocation(contents) {
+  for (const rawLine of contents.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice('export '.length).trim();
+    const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
+    if (assignment) line = assignment[1].trim();
+    if (
+      (line.startsWith('"') && line.endsWith('"')) ||
+      (line.startsWith("'") && line.endsWith("'"))
+    ) {
+      line = line.slice(1, -1);
+    }
+    return line.length > 0 ? line : null;
+  }
+  return null;
+}
+
+export function readProjectArtifactLocation(projectDir) {
+  const pointerPath = resolve(projectDir, PROJECT_AIWG_LOCATION_FILE);
+  if (!existsSync(pointerPath)) return null;
+  return parseProjectArtifactLocation(readFileSync(pointerPath, 'utf-8'));
+}
+
+export function resolveProjectAiwgDir(projectDir, env = process.env) {
+  for (const key of ARTIFACT_PATH_ENV_ALIASES) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return expandProjectArtifactPath(value, projectDir);
+    }
+  }
+  const configuredLocation = readProjectArtifactLocation(projectDir);
+  if (configuredLocation) return expandProjectArtifactPath(configuredLocation, projectDir);
+  return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
+}
+
+export function projectAiwgPath(projectDir, ...segments) {
+  return join(resolveProjectAiwgDir(projectDir), ...segments);
+}

package/dist/src/config/project-artifacts.js

@@ -5,72 +5,5 @@
  * override for the project-local `.aiwg/` artifact root. Keep that contract
  * centralized so callers do not hardcode `<project>/.aiwg`.
  */
-import { homedir } from 'os';
-import { existsSync, readFileSync } from 'fs';
-import { isAbsolute, join, resolve } from 'path';
-export const DEFAULT_PROJECT_AIWG_DIR = '.aiwg';
-export const AIWG_ARTIFACTS_PATH_ENV = 'AIWG_ARTIFACTS_PATH';
-export const PROJECT_AIWG_LOCATION_FILE = '.aiwg-location';
-const ARTIFACT_PATH_ENV_ALIASES = [
-    AIWG_ARTIFACTS_PATH_ENV,
-    'AIWG_PROJECT_ARTIFACTS_PATH',
-    'AIWG_PROJECT_AIWG_DIR',
-];
-export function expandProjectArtifactPath(pathValue, projectDir) {
-    const trimmed = pathValue.trim();
-    if (trimmed === '~')
-        return homedir();
-    if (trimmed.startsWith('~/'))
-        return resolve(homedir(), trimmed.slice(2));
-    if (isAbsolute(trimmed))
-        return trimmed;
-    return resolve(projectDir, trimmed);
-}
-export function parseProjectArtifactLocation(contents) {
-    for (const rawLine of contents.split(/\r?\n/)) {
-        let line = rawLine.trim();
-        if (line.length === 0 || line.startsWith('#'))
-            continue;
-        if (line.startsWith('export '))
-            line = line.slice('export '.length).trim();
-        const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
-        if (assignment)
-            line = assignment[1].trim();
-        if ((line.startsWith('"') && line.endsWith('"')) ||
-            (line.startsWith("'") && line.endsWith("'"))) {
-            line = line.slice(1, -1);
-        }
-        return line.length > 0 ? line : null;
-    }
-    return null;
-}
-export function readProjectArtifactLocation(projectDir) {
-    const pointerPath = resolve(projectDir, PROJECT_AIWG_LOCATION_FILE);
-    if (!existsSync(pointerPath))
-        return null;
-    return parseProjectArtifactLocation(readFileSync(pointerPath, 'utf-8'));
-}
-/**
- * Resolve the directory that contains AIWG project artifacts.
- *
- * Defaults to `<projectDir>/.aiwg`. When `AIWG_ARTIFACTS_PATH` is set, the
- * override may be absolute, project-relative, or `~/`-relative. The override
- * intentionally points at the artifact directory itself, not its parent, so
- * callers can rename `.aiwg` or place it outside the checkout.
- */
-export function resolveProjectAiwgDir(projectDir, env = process.env) {
-    for (const key of ARTIFACT_PATH_ENV_ALIASES) {
-        const value = env[key];
-        if (typeof value === 'string' && value.trim().length > 0) {
-            return expandProjectArtifactPath(value, projectDir);
-        }
-    }
-    const configuredLocation = readProjectArtifactLocation(projectDir);
-    if (configuredLocation)
-        return expandProjectArtifactPath(configuredLocation, projectDir);
-    return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
-}
-export function projectAiwgPath(projectDir, ...segments) {
-    return join(resolveProjectAiwgDir(projectDir), ...segments);
-}
+export { AIWG_ARTIFACTS_PATH_ENV, DEFAULT_PROJECT_AIWG_DIR, PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, parseProjectArtifactLocation, projectAiwgPath, readProjectArtifactLocation, resolveProjectAiwgDir, } from './project-artifacts-runtime.mjs';
 //# sourceMappingURL=project-artifacts.js.map