@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/config/user-registry.js

@@ -0,0 +1,127 @@
+/**
+ * Per-user AIWG registry — `~/.aiwg/installed.json` (#1156 Phase 1).
+ *
+ * Tracks frameworks/addons deployed at user scope (`aiwg use --scope user`).
+ * Operationally distinct from the project-level `.aiwg/aiwg.config`:
+ *
+ *   project:      .aiwg/aiwg.config           — installed.{name}
+ *   user:         ~/.aiwg/installed.json      — installed.{name}.deployedTo.{provider}
+ *
+ * Same shape as `AiwgConfig.installed` so existing helpers can be lifted with
+ * minimal change. The user registry exists outside any project so `aiwg list
+ * --scope user` works from any cwd.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { userScopeConfigPath } from '../cli/scope-resolver.js';
+/**
+ * Path to ~/.aiwg/installed.json. Distinct from `userScopeConfigPath()`
+ * (which points at ~/.aiwg/aiwg.config and is reserved for future user-level
+ * config that mirrors the project aiwg.config structure).
+ *
+ * Honors `AIWG_USER_REGISTRY_PATH` for test isolation: setting that env var
+ * redirects all reads/writes to the supplied path. Production code should
+ * never set this — it exists so the test suite can avoid clobbering the real
+ * `~/.aiwg/installed.json` on the developer's machine.
+ */
+export function userRegistryPath() {
+    const override = process.env.AIWG_USER_REGISTRY_PATH;
+    if (override)
+        return override;
+    // Reuse the directory portion of userScopeConfigPath() to stay consistent
+    // with the documented user-scope convention from ADR-4.
+    return dirname(userScopeConfigPath()) + '/installed.json';
+}
+export function emptyUserRegistry() {
+    return { version: '1', installed: {} };
+}
+/**
+ * Read the per-user registry. Returns an empty registry when the file doesn't
+ * exist — that's the normal case before the operator's first `aiwg use --scope
+ * user`. On parse failure returns the empty registry and writes a stderr
+ * warning (the broken file is preserved so the operator can inspect it).
+ */
+export async function readUserRegistry() {
+    const path = userRegistryPath();
+    if (!existsSync(path))
+        return emptyUserRegistry();
+    try {
+        const raw = await readFile(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.installed || typeof parsed.installed !== 'object') {
+            return emptyUserRegistry();
+        }
+        return { version: '1', installed: parsed.installed };
+    }
+    catch (err) {
+        process.stderr.write(`[user-registry] failed to parse ${path}: ${err instanceof Error ? err.message : String(err)} — using empty registry\n`);
+        return emptyUserRegistry();
+    }
+}
+/**
+ * Persist the user registry. Creates the parent directory if missing.
+ */
+export async function writeUserRegistry(registry) {
+    const path = userRegistryPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Record a successful user-scope deploy. Idempotent — re-running `aiwg use
+ * --scope user` for the same framework+provider overwrites the prior entry's
+ * counts, entries, and timestamp.
+ *
+ * Mutates the passed registry in place AND writes it to disk so callers don't
+ * have to manage the persistence dance themselves.
+ *
+ * `entries` (optional) records the actual artifact names this deploy
+ * mirrored, enabling precise remove later.
+ */
+export async function recordUserDeploy(opts) {
+    const registry = await readUserRegistry();
+    const existing = registry.installed[opts.framework];
+    const deployedTo = existing?.deployedTo ?? {};
+    // Merge the new counts with the optional entries snapshot. Cast through
+    // UserScopeProviderDeploy so the registry can carry the richer shape.
+    const merged = { ...opts.counts };
+    if (opts.entries)
+        merged.entries = opts.entries;
+    deployedTo[opts.provider] = merged;
+    registry.installed[opts.framework] = {
+        version: opts.version,
+        source: opts.source,
+        installedAt: new Date().toISOString(),
+        deployedTo,
+        manifestHash: opts.manifestHash,
+    };
+    await writeUserRegistry(registry);
+    return registry;
+}
+/**
+ * Remove a framework's user-scope deploy from the registry. If `provider` is
+ * specified, removes only that provider's entry; the framework entry stays if
+ * other providers remain. Without `provider`, removes the framework entirely.
+ *
+ * Returns the updated registry. The caller is responsible for the actual
+ * filesystem revert (deleting the mirrored artifacts) — this only updates the
+ * bookkeeping.
+ */
+export async function removeUserDeploy(opts) {
+    const registry = await readUserRegistry();
+    const entry = registry.installed[opts.framework];
+    if (!entry)
+        return registry;
+    if (opts.provider) {
+        delete entry.deployedTo[opts.provider];
+        if (Object.keys(entry.deployedTo).length === 0) {
+            delete registry.installed[opts.framework];
+        }
+    }
+    else {
+        delete registry.installed[opts.framework];
+    }
+    await writeUserRegistry(registry);
+    return registry;
+}
+//# sourceMappingURL=user-registry.js.map

package/dist/src/config/workspace.js

@@ -0,0 +1,276 @@
+/**
+ * General workspace-of-repositories resolution.
+ *
+ * A workspace root declares members in its `.aiwg/aiwg.config`. Every member
+ * keeps its own `.aiwg/aiwg.config`; that member config is authoritative for
+ * delivery, remotes, tracker actor, and signing. Workspace capabilities are an
+ * additional deny-by-default authorization layer.
+ *
+ * @implements #1764
+ */
+import { execFile } from 'child_process';
+import { existsSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, isAbsolute, relative, resolve } from 'path';
+import { promisify } from 'util';
+import { getConfigPath, readAiwgConfig, resolveDelivery, resolveRemoteProvider, resolveRemotes, } from './aiwg-config.js';
+const execFileAsync = promisify(execFile);
+function expandHome(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/') || value.startsWith('~\\')) {
+        return resolve(homedir(), value.slice(2));
+    }
+    return value;
+}
+function asDirectory(value) {
+    const absolute = resolve(value);
+    try {
+        return statSync(absolute).isDirectory() ? absolute : dirname(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function isSameOrInside(candidate, root) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function resolveFrom(base, value) {
+    const expanded = expandHome(value);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(base, expanded);
+}
+/**
+ * Find the workspace root that governs `startPath`.
+ *
+ * Child members discover an ancestor workspace naturally. External members
+ * can set `workspace.member_of`, or callers can set AIWG_WORKSPACE / pass an
+ * explicit workspace root.
+ */
+export async function findWorkspaceProjectRoot(startPath = process.cwd(), explicitWorkspace) {
+    const override = explicitWorkspace ?? process.env.AIWG_WORKSPACE;
+    if (override) {
+        const projectRoot = asDirectory(expandHome(override));
+        const config = await readAiwgConfig(projectRoot);
+        if (!config?.repos) {
+            throw new Error(`Workspace config at ${getConfigPath(projectRoot)} does not declare repos`);
+        }
+        return projectRoot;
+    }
+    let current = asDirectory(startPath);
+    while (true) {
+        if (existsSync(getConfigPath(current))) {
+            const config = await readAiwgConfig(current);
+            if (config?.repos)
+                return current;
+            if (config?.workspace?.member_of) {
+                const projectRoot = resolveFrom(current, config.workspace.member_of);
+                const workspaceConfig = await readAiwgConfig(projectRoot);
+                if (!workspaceConfig?.repos) {
+                    throw new Error(`workspace.member_of resolves to ${projectRoot}, but its .aiwg/aiwg.config does not declare repos`);
+                }
+                return projectRoot;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function remoteDomain(remoteUrl) {
+    if (!remoteUrl)
+        return undefined;
+    const scp = remoteUrl.match(/^[^@/\s]+@([^:/\s]+):/);
+    if (scp?.[1])
+        return scp[1].toLowerCase();
+    try {
+        const parsed = new URL(remoteUrl);
+        return parsed.hostname.toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readRemoteUrl(repoPath, remote) {
+    if (remote.includes('://') || /^[^@/\s]+@[^:/\s]+:/.test(remote))
+        return remote;
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', repoPath, 'remote', 'get-url', remote], { encoding: 'utf8' });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolveEndpoint(repoPath, remote, providerHint) {
+    const url = await readRemoteUrl(repoPath, remote);
+    const detected = resolveRemoteProvider(url ?? '');
+    const provider = detected === 'unknown' && providerHint ? providerHint : detected;
+    return {
+        name: remote,
+        ...(url ? { url } : {}),
+        provider,
+        ...(remoteDomain(url) ? { domain: remoteDomain(url) } : {}),
+        providerSource: detected !== 'unknown'
+            ? 'remote'
+            : providerHint
+                ? 'manifest-hint'
+                : 'unknown',
+    };
+}
+async function resolveMember(entry, workspaceRoot) {
+    const memberPath = resolveFrom(workspaceRoot, entry.path);
+    const configPath = getConfigPath(memberPath);
+    const config = await readAiwgConfig(memberPath);
+    const remotes = resolveRemotes(config?.remotes);
+    const [primary, issueTracker, ci] = await Promise.all([
+        resolveEndpoint(memberPath, remotes.primary, entry.provider),
+        resolveEndpoint(memberPath, remotes.issue_tracker, entry.provider),
+        resolveEndpoint(memberPath, remotes.ci, entry.provider),
+    ]);
+    const drift = [];
+    if (!existsSync(memberPath))
+        drift.push('member path is missing');
+    if (!config)
+        drift.push('member .aiwg/aiwg.config is missing');
+    if (!primary.url)
+        drift.push(`primary remote '${remotes.primary}' is unavailable`);
+    if (!issueTracker.url)
+        drift.push(`issue tracker remote '${remotes.issue_tracker}' is unavailable`);
+    if (primary.provider === 'unknown') {
+        drift.push(`primary remote provider is unknown for '${primary.domain ?? remotes.primary}'`);
+    }
+    if (issueTracker.provider === 'unknown') {
+        drift.push(`issue tracker provider is unknown for '${issueTracker.domain ?? remotes.issue_tracker}'`);
+    }
+    if (entry.allowed.includes('issue-comment') && !remotes.tracker_actor?.login) {
+        drift.push('issue-comment is allowed but remotes.tracker_actor.login is missing');
+    }
+    if (remotes.tracker_actor?.login
+        && remotes.tracker_actor.forbid_actors?.includes(remotes.tracker_actor.login)) {
+        drift.push(`configured tracker actor '${remotes.tracker_actor.login}' is also forbidden`);
+    }
+    if (config?.delivery?.signing?.enforce
+        && !config.delivery.signing.key
+        && !config.delivery.signing.key_file) {
+        drift.push('delivery signing is enforced but no key or key_file is configured');
+    }
+    if (entry.provider && primary.providerSource === 'remote' && primary.provider !== entry.provider) {
+        drift.push(`provider hint '${entry.provider}' disagrees with primary remote provider '${primary.provider}'`);
+    }
+    return {
+        name: entry.name,
+        path: memberPath,
+        allowed: [...entry.allowed],
+        ...(entry.notes ? { notes: entry.notes } : {}),
+        configPath,
+        config,
+        delivery: resolveDelivery(config?.delivery),
+        remotes,
+        primary,
+        issueTracker,
+        ci,
+        drift,
+    };
+}
+/** Load and resolve every member from the canonical workspace manifest. */
+export async function resolveWorkspace(startPath = process.cwd(), explicitWorkspace) {
+    const projectRoot = await findWorkspaceProjectRoot(startPath, explicitWorkspace);
+    if (!projectRoot) {
+        throw new Error('No workspace .aiwg/aiwg.config with repos was found');
+    }
+    const config = await readAiwgConfig(projectRoot);
+    if (!config?.repos || !config.workspace?.name) {
+        throw new Error(`Invalid workspace config at ${getConfigPath(projectRoot)}`);
+    }
+    const workspaceRoot = config.workspace.root
+        ? resolveFrom(projectRoot, config.workspace.root)
+        : projectRoot;
+    const members = await Promise.all(config.repos.map((entry) => resolveMember(entry, workspaceRoot)));
+    return {
+        name: config.workspace.name,
+        projectRoot,
+        root: workspaceRoot,
+        configPath: getConfigPath(projectRoot),
+        config,
+        members,
+    };
+}
+/** Resolve the most-specific workspace member containing a target path. */
+export async function resolveWorkspaceMember(startPath, targetPath = startPath, explicitWorkspace) {
+    const workspace = await resolveWorkspace(startPath, explicitWorkspace);
+    const target = isAbsolute(targetPath)
+        ? resolve(targetPath)
+        : resolve(asDirectory(startPath), targetPath);
+    const member = workspace.members
+        .filter((candidate) => isSameOrInside(target, candidate.path))
+        .sort((a, b) => b.path.length - a.path.length)[0] ?? null;
+    return { workspace, member };
+}
+/**
+ * Apply workspace authorization to an operation. An unlisted target or a
+ * missing action is denied regardless of filesystem/tool writability.
+ */
+export async function authorizeWorkspaceOperation(startPath, targetPath, action, explicitWorkspace) {
+    const requestedPath = isAbsolute(targetPath)
+        ? resolve(targetPath)
+        : resolve(asDirectory(startPath), targetPath);
+    const { member } = await resolveWorkspaceMember(startPath, requestedPath, explicitWorkspace);
+    if (!member) {
+        return {
+            allowed: false,
+            action,
+            requestedPath,
+            member: null,
+            reason: 'unlisted repo/path defaults to denied',
+        };
+    }
+    if (!member.allowed.includes(action)) {
+        return {
+            allowed: false,
+            action,
+            requestedPath,
+            member,
+            reason: `repo '${member.name}' does not allow ${action}`,
+        };
+    }
+    return {
+        allowed: true,
+        action,
+        requestedPath,
+        member,
+        reason: `repo '${member.name}' allows ${action}`,
+    };
+}
+/** Enforce the member config tracker_actor + forbid_actors contract. */
+export function checkTrackerActor(member, actualActor) {
+    const configured = member.remotes.tracker_actor;
+    const actor = actualActor ?? configured?.login;
+    if (!actor) {
+        return {
+            allowed: false,
+            reason: `repo '${member.name}' does not resolve a tracker actor`,
+        };
+    }
+    if (configured?.forbid_actors?.includes(actor)) {
+        return {
+            allowed: false,
+            actor,
+            reason: `tracker actor '${actor}' is forbidden by repo '${member.name}'`,
+        };
+    }
+    if (actualActor && configured?.login && actualActor !== configured.login) {
+        return {
+            allowed: false,
+            actor,
+            reason: `tracker actor '${actualActor}' does not match configured actor '${configured.login}'`,
+        };
+    }
+    return {
+        allowed: true,
+        actor,
+        reason: `tracker actor '${actor}' is allowed for repo '${member.name}'`,
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/src/contributors/detect.js

@@ -0,0 +1,39 @@
+/**
+ * Contributor Detection Runner
+ *
+ * Runs a contributor's declarative detection spec against the project root.
+ * Determines whether the contributor's framework is *in use* on this project,
+ * not just installed. Pure I/O — no code execution.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #938
+ */
+import { glob } from 'glob';
+/**
+ * Run a contributor's detection spec. Returns the count of files matching
+ * any glob pattern (with deduplication). The caller compares against
+ * `spec.minCount` to decide in-use status.
+ */
+export async function runDetection(spec, projectRoot) {
+    const seen = new Set();
+    for (const pattern of spec.glob) {
+        const matches = await glob(pattern, {
+            cwd: projectRoot,
+            nodir: true,
+            dot: false,
+            absolute: false,
+        });
+        for (const m of matches)
+            seen.add(m);
+    }
+    return seen.size;
+}
+/**
+ * Convenience wrapper: returns true when match count meets minCount (default 1).
+ */
+export async function isInUse(spec, projectRoot) {
+    const min = spec.minCount ?? 1;
+    const count = await runDetection(spec, projectRoot);
+    return count >= min;
+}
+//# sourceMappingURL=detect.js.map

package/dist/src/contributors/discover.js

@@ -0,0 +1,172 @@
+/**
+ * Contributor Discovery
+ *
+ * Walks the installed framework registry and project-local override directory
+ * to find `<framework>/<kind>/contributor.md` files. Parses, validates, and
+ * runs detection on each candidate. Returns kept records and skipped entries
+ * with reasons. Failures of one contributor never abort discovery.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #938
+ */
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { glob } from 'glob';
+import path from 'path';
+import { parseFrontmatter } from '../artifacts/index-builder.js';
+import { projectAiwgPath } from '../config/project-artifacts.js';
+import { isInUse } from './detect.js';
+import { validateContributor } from './validation.js';
+/**
+ * Subdirectories under a framework root that may host installable units.
+ * The discovery loop checks each in order so a single id can resolve to
+ * the right source path regardless of whether it's a framework, addon, or
+ * extension. First match wins.
+ */
+const FRAMEWORK_SUBDIRS = ['frameworks', 'addons', 'extensions'];
+/**
+ * Read the registry. Returns empty list if missing or unparseable — discovery
+ * is non-fatal and project-local contributors can still be found.
+ */
+async function readRegistry(registryPath) {
+    if (!existsSync(registryPath))
+        return { frameworks: [] };
+    try {
+        const raw = await readFile(registryPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && Array.isArray(parsed.frameworks) ? parsed : { frameworks: [] };
+    }
+    catch {
+        return { frameworks: [] };
+    }
+}
+/**
+ * Resolve a framework id to its source path under the AIWG installation.
+ * Tries `frameworks/`, `addons/`, `extensions/` in order. Returns null if
+ * none exist on disk — the id is registered but its source is missing.
+ */
+function resolveFrameworkSourcePath(frameworkRoot, id) {
+    for (const sub of FRAMEWORK_SUBDIRS) {
+        const candidate = path.join(frameworkRoot, 'agentic', 'code', sub, id);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Process one contributor source: parse, validate, run detection.
+ * Returns either a record (in-use) or a skip entry. Never throws.
+ */
+async function processContributor(src, projectRoot) {
+    let raw;
+    try {
+        raw = await readFile(src.path, 'utf-8');
+    }
+    catch (err) {
+        return {
+            kind: 'skip',
+            entry: { ...src, reason: 'parse-error', message: `cannot read file: ${err.message}` },
+        };
+    }
+    let data;
+    let body;
+    try {
+        const parsed = parseFrontmatter(raw);
+        data = parsed.data;
+        body = parsed.body;
+    }
+    catch (err) {
+        return {
+            kind: 'skip',
+            entry: { ...src, reason: 'parse-error', message: `cannot parse frontmatter: ${err.message}` },
+        };
+    }
+    const validation = validateContributor(data);
+    if (!validation.ok) {
+        return {
+            kind: 'skip',
+            entry: { ...src, reason: 'schema-violation', message: validation.errors.join('; ') },
+        };
+    }
+    const validData = validation.data;
+    let inUse;
+    try {
+        inUse = await isInUse(validData.detect, projectRoot);
+    }
+    catch (err) {
+        return {
+            kind: 'skip',
+            entry: { ...src, reason: 'detection-error', message: `detection threw: ${err.message}` },
+        };
+    }
+    if (!inUse) {
+        return {
+            kind: 'skip',
+            entry: { ...src, reason: 'detection-no-match', message: 'declared globs matched fewer files than minCount' },
+        };
+    }
+    return {
+        kind: 'record',
+        record: { ...src, data: validData, body },
+    };
+}
+/**
+ * Discover all in-use contributors of a given kind for a project.
+ *
+ * Walks two source classes:
+ *
+ *   1. Framework-shipped contributors — for each framework id in the project's
+ *      `.aiwg/frameworks/registry.json`, look up its source path under the
+ *      AIWG installation and check for `<kind>/contributor.md`.
+ *
+ *   2. Project-local contributors — every `.aiwg/contributors/<kind>/*.md`
+ *      file in the project root. Lets users add custom contributors without
+ *      forking a framework.
+ *
+ * Order is preserved: framework contributors appear in registry order, then
+ * project-local contributors in glob order. Each kept record carries its
+ * `origin` (framework id or `'project-local'`) and absolute `path`.
+ *
+ * Failures (parse, validation, detection-throw, detection-no-match) are
+ * captured as `SkippedContributor` entries — discovery never aborts on a
+ * single bad contributor.
+ */
+export async function discoverContributors(kind, options) {
+    const { frameworkRoot, projectRoot } = options;
+    const registryPath = options.registryPath ?? projectAiwgPath(projectRoot, 'frameworks', 'registry.json');
+    const sources = [];
+    // 1. Framework-shipped contributors via registry.
+    const registry = await readRegistry(registryPath);
+    for (const entry of registry.frameworks) {
+        const sourcePath = resolveFrameworkSourcePath(frameworkRoot, entry.id);
+        if (!sourcePath)
+            continue;
+        const candidate = path.join(sourcePath, kind, 'contributor.md');
+        if (existsSync(candidate)) {
+            sources.push({ origin: entry.id, path: candidate });
+        }
+    }
+    // 2. Project-local contributors.
+    const localDir = projectAiwgPath(projectRoot, 'contributors', kind);
+    if (existsSync(localDir)) {
+        const localFiles = await glob('*.md', { cwd: localDir, absolute: true, nodir: true });
+        localFiles.sort(); // deterministic ordering
+        for (const file of localFiles) {
+            sources.push({ origin: 'project-local', path: file });
+        }
+    }
+    // Process each source. Failures become skip entries; the rest become records.
+    const records = [];
+    const skipped = [];
+    for (const src of sources) {
+        const result = await processContributor(src, projectRoot);
+        if (result.kind === 'record') {
+            records.push(result.record);
+        }
+        else {
+            skipped.push(result.entry);
+        }
+    }
+    return { kind, records, skipped };
+}
+//# sourceMappingURL=discover.js.map