@ai-outfitter/outfitter 1.5.0 → 1.6.0

package/dist/setup/DefaultCatalog.js

@@ -1,24 +1,37 @@
 // Bootstraps the one canonical default catalog at the immutable revision shipped by Outfitter.
-import { existsSync } from 'node:fs';
+import { statSync } from 'node:fs';
 import { join } from 'node:path';
 import { runGit, syncRemoteRepositoryAtomically, tryReadCleanHead } from '../sources/GitRepository.js';
-import { createRemoteRepositoryCachePath, redactEmbeddedSourceCredentials } from '../sources/SourceCache.js';
+import { createRemoteRepositoryCachePath, encodeRemoteSourceSelection, formatRemoteSourceDisplay, isImmutableRef, isVersionTagRef, redactEmbeddedSourceCredentials, } from '../sources/SourceCache.js';
+import { readDeclaredRemoteSources } from '../sources/TransitiveSources.js';
 export const defaultCatalogSource = {
     github: 'ai-outfitter/default-profiles',
     // TODO(release-automation): when default-profiles publishes a new Release Please tag, open a
     // conventional dependency-bump commit in Outfitter so its next Release Please release ships it.
     ref: 'v1.1.0',
 };
-const fullCommitPattern = /^[a-f0-9]{40}$/u;
-const versionTagPattern = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+// A recognized payload marker must be a real directory, not merely a path that exists: a repository
+// committing a regular file named `agents` is not a catalog and must not validate as one.
+const isDirectory = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const hasAgentsDirectory = (root) => isDirectory(join(root, 'agents'));
+// Any directory the resolver treats as a `.agents` payload container, colocated or at the root.
+const hasAnyAgentsPayload = (root) => ['agents', 'skills', 'knowledge', 'commands'].some((directory) => isDirectory(join(root, directory))) ||
+    isDirectory(join(root, '.agents'));
 const assertImmutableRef = (ref) => {
-    if (!fullCommitPattern.test(ref) && !versionTagPattern.test(ref)) {
+    if (!isImmutableRef(ref)) {
         throw new Error(`Default catalog ref '${ref}' must be a full commit SHA or version tag.`);
     }
 };
-const resolveExpectedCommit = (root, ref) => fullCommitPattern.test(ref) ? ref : runGit(['-C', root, 'rev-parse', `refs/tags/${ref}^{commit}`]);
-const isPinnedCatalogCheckout = (root, ref) => {
-    if (!existsSync(join(root, 'agents')))
+const resolveExpectedCommit = (root, ref) => isVersionTagRef(ref) ? runGit(['-C', root, 'rev-parse', `refs/tags/${ref}^{commit}`]) : ref;
+const isPinnedCatalogCheckout = (root, ref, hasPayload) => {
+    if (!hasPayload(root))
         return false;
     try {
         return tryReadCleanHead(root) === resolveExpectedCommit(root, ref);
@@ -30,13 +43,14 @@ const isPinnedCatalogCheckout = (root, ref) => {
 /** Fetches one immutable catalog revision into the same cache path used by normal source resolution. */
 export const bootstrapPinnedCatalog = (input) => {
     assertImmutableRef(input.source.ref);
+    const hasPayload = input.requirePayload ?? hasAgentsDirectory;
     const root = createRemoteRepositoryCachePath(input.homeDirectory, input.source, input.cacheDirectory);
-    if (isPinnedCatalogCheckout(root, input.source.ref))
+    if (isPinnedCatalogCheckout(root, input.source.ref, hasPayload))
         return { root, source: input.source };
     try {
-        syncRemoteRepositoryAtomically({
+        (input.syncRepository ?? syncRemoteRepositoryAtomically)({
             cachePath: root,
-            fetchRef: versionTagPattern.test(input.source.ref)
+            fetchRef: isVersionTagRef(input.source.ref)
                 ? `refs/tags/${input.source.ref}:refs/tags/${input.source.ref}`
                 : input.source.ref,
             source: input.source,
@@ -45,7 +59,7 @@ export const bootstrapPinnedCatalog = (input) => {
             // accepting a dirty tree here would cache one that `tryReadCleanHead` rejects on every
             // subsequent read, re-fetching forever.
             validate: (temporaryRoot) => {
-                if (!isPinnedCatalogCheckout(temporaryRoot, input.source.ref)) {
+                if (!isPinnedCatalogCheckout(temporaryRoot, input.source.ref, hasPayload)) {
                     throw new Error(`Fetched default catalog did not resolve to ${input.source.ref}.`);
                 }
                 return 0;
@@ -60,5 +74,52 @@ export const bootstrapPinnedCatalog = (input) => {
         });
     }
 };
-export const bootstrapDefaultCatalog = (homeDirectory, cacheDirectory) => bootstrapPinnedCatalog({ homeDirectory, cacheDirectory, source: defaultCatalogSource });
+/**
+ * Bootstraps a pinned catalog and the pinned `github:` closure it declares, so a fresh install can
+ * resolve a default profile whose skills live in a depended-on catalog (the founder profile's
+ * persona skills, shipped by community-profiles) without a manual `outfitter sync`. The root failing
+ * to fetch is fatal (existing behavior); a declared dependency failing to fetch is best-effort —
+ * resolution reports it as unsynchronized rather than blocking setup on it.
+ */
+export const bootstrapPinnedClosure = (input) => {
+    const rootResult = bootstrapPinnedCatalog(input);
+    const visited = new Set([encodeRemoteSourceSelection(input.source)]);
+    let frontier = [
+        { root: rootResult.root, label: formatRemoteSourceDisplay(input.source) },
+    ];
+    while (frontier.length > 0) {
+        const next = [];
+        for (const parent of frontier) {
+            // A `github:` closure is always path-less, so the payload root is the checkout root.
+            for (const declared of readDeclaredRemoteSources(parent.root, parent.root, parent.label).sources) {
+                const key = encodeRemoteSourceSelection(declared.source);
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                try {
+                    next.push({
+                        root: bootstrapPinnedCatalog({
+                            homeDirectory: input.homeDirectory,
+                            cacheDirectory: input.cacheDirectory,
+                            source: declared.source,
+                            syncRepository: input.syncRepository,
+                            // A dependency may ship only skills; do not require it to contain agents/.
+                            requirePayload: hasAnyAgentsPayload,
+                        }).root,
+                        label: formatRemoteSourceDisplay(declared.source),
+                    });
+                }
+                catch {
+                    // Best-effort: a dependency that cannot be fetched is surfaced by resolution as an
+                    // unsynchronized source (with `outfitter sync` guidance), never a setup-blocking throw.
+                }
+            }
+        }
+        frontier = next;
+    }
+    return rootResult;
+};
+/* v8 ignore next 2 -- the production entry fetches the real default catalog from github.com; tests
+   drive bootstrapPinnedClosure directly and SetupCommand injects a fake bootstrap. */
+export const bootstrapDefaultCatalog = (homeDirectory, cacheDirectory) => bootstrapPinnedClosure({ homeDirectory, cacheDirectory, source: defaultCatalogSource });
 //# sourceMappingURL=DefaultCatalog.js.map

package/dist/setup/DefaultCatalog.js.map

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

package/dist/sources/SourceCache.d.ts

@@ -15,6 +15,10 @@ export declare const isRemoteSource: <T extends {
     readonly uri?: string;
     readonly github?: string;
 }>(source: T) => source is T & RemoteSourceReference;
+/** True for a ref that names one immutable revision: a full commit SHA or a version tag. */
+export declare const isImmutableRef: (ref: string) => boolean;
+/** True for an immutable ref that must be resolved to a commit via `rev-parse` (a version tag). */
+export declare const isVersionTagRef: (ref: string) => boolean;
 export declare const normalizeGitUri: (uri: string) => string;
 export declare const normalizeRemoteSourceUri: (source: RemoteSourceReference) => string;
 export declare const formatRemoteSourceDisplay: (source: RemoteSourceReference) => string;
@@ -23,7 +27,23 @@ export declare const redactSourceUriCredentials: (uri: string) => string;
 export declare const redactEmbeddedSourceCredentials: (value: string) => string;
 export declare const encodeSourceUri: (uri: string) => string;
 export declare const encodeRemoteSource: (source: RemoteSourceReference) => string;
+/**
+ * A source's graph identity for dedup, visited sets, and layer ordering. It differs from
+ * {@link encodeRemoteSource} (the *checkout cache* key) in two deliberate ways:
+ *
+ * - It includes the canonicalized `path`, because two sources into different subpaths of one repo+ref
+ *   are distinct layers — deduping them on the path-less cache key would silently drop one.
+ * - It keys on the *raw* normalized URI, credentials included, not the redacted cache key. Two entries
+ *   for the same repo with different credentials are distinct configured sources; collapsing them
+ *   (the cache key redacts credentials, so both share it) could drop a valid source for a broken one.
+ *   This value is used only in ephemeral in-memory dedup/visited sets — never persisted or logged —
+ *   so carrying credentials here is safe (the cache path and every user-facing display use the
+ *   redacted forms).
+ */
+export declare const encodeRemoteSourceSelection: (source: RemoteSourceReference) => string;
 /** Resolves the one cache root used by sync, settings, layer discovery, and setup bootstrap. */
 export declare const resolveRemoteRepositoryCacheRoot: (homeDirectory: string, cacheDirectory?: string) => string;
 export declare const createRemoteRepositoryCachePath: (homeDirectory: string, source: RemoteSourceReference, cacheDirectory?: string) => string;
+/** The `.agents` payload root a source selects inside its materialized repository checkout. */
+export declare const resolveSourcePayloadRoot: (repositoryPath: string, source: RemoteSourceReference) => string;
 export declare const resolveRemoteRepositorySubpath: (repositoryPath: string, subpath?: string) => string;

package/dist/sources/SourceCache.js

@@ -1,7 +1,13 @@
 // Encodes remote `.agents` source cache paths and normalizes remote source references.
-import { isAbsolute, join, relative, resolve } from 'node:path';
+import { isAbsolute, join, posix, relative, resolve } from 'node:path';
 /** Distinguishes remote (`uri`/`github`) sources from local `path` sources. */
 export const isRemoteSource = (source) => source.uri !== undefined || source.github !== undefined;
+const fullCommitPattern = /^[a-f0-9]{40}$/u;
+const versionTagPattern = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+/** True for a ref that names one immutable revision: a full commit SHA or a version tag. */
+export const isImmutableRef = (ref) => fullCommitPattern.test(ref) || versionTagPattern.test(ref);
+/** True for an immutable ref that must be resolved to a commit via `rev-parse` (a version tag). */
+export const isVersionTagRef = (ref) => versionTagPattern.test(ref);
 export const normalizeGitUri = (uri) => (uri.startsWith('git+') ? uri.slice('git+'.length) : uri);
 export const normalizeRemoteSourceUri = (source) => {
     if (source.uri !== undefined) {
@@ -32,9 +38,33 @@ export const redactSourceUriCredentials = (uri) => {
 export const redactEmbeddedSourceCredentials = (value) => value.replace(/((?:git\+)?[A-Za-z][A-Za-z0-9+.-]*:\/\/)[^/@\s]+@/gu, '$1REDACTED@');
 export const encodeSourceUri = (uri) => Buffer.from(redactSourceUriCredentials(uri), 'utf8').toString('base64url');
 export const encodeRemoteSource = (source) => encodeSourceUri(`${normalizeRemoteSourceUri(source)}#${source.ref ?? ''}`);
+// The payload subpath a source selects, canonicalized so identical selections share one identity:
+// an omitted path, `.`, `./`, and `foo/..` all normalize to the repository root ('').
+const canonicalSourcePath = (path) => {
+    if (path === undefined)
+        return '';
+    const normalized = posix.normalize(path).replace(/\/+$/u, '');
+    return normalized === '.' ? '' : normalized;
+};
+/**
+ * A source's graph identity for dedup, visited sets, and layer ordering. It differs from
+ * {@link encodeRemoteSource} (the *checkout cache* key) in two deliberate ways:
+ *
+ * - It includes the canonicalized `path`, because two sources into different subpaths of one repo+ref
+ *   are distinct layers — deduping them on the path-less cache key would silently drop one.
+ * - It keys on the *raw* normalized URI, credentials included, not the redacted cache key. Two entries
+ *   for the same repo with different credentials are distinct configured sources; collapsing them
+ *   (the cache key redacts credentials, so both share it) could drop a valid source for a broken one.
+ *   This value is used only in ephemeral in-memory dedup/visited sets — never persisted or logged —
+ *   so carrying credentials here is safe (the cache path and every user-facing display use the
+ *   redacted forms).
+ */
+export const encodeRemoteSourceSelection = (source) => `${normalizeRemoteSourceUri(source)}#${source.ref ?? ''} ${canonicalSourcePath(source.path)}`;
 /** Resolves the one cache root used by sync, settings, layer discovery, and setup bootstrap. */
 export const resolveRemoteRepositoryCacheRoot = (homeDirectory, cacheDirectory) => cacheDirectory ?? join(homeDirectory, '.agents', 'cache');
 export const createRemoteRepositoryCachePath = (homeDirectory, source, cacheDirectory) => join(resolveRemoteRepositoryCacheRoot(homeDirectory, cacheDirectory), 'repos', encodeRemoteSource(source));
+/** The `.agents` payload root a source selects inside its materialized repository checkout. */
+export const resolveSourcePayloadRoot = (repositoryPath, source) => source.path === undefined ? repositoryPath : resolveRemoteRepositorySubpath(repositoryPath, source.path);
 export const resolveRemoteRepositorySubpath = (repositoryPath, subpath = '') => {
     if (isAbsolute(subpath)) {
         throw new Error(`Remote repository path '${subpath}' must be relative.`);

package/dist/sources/SourceCache.js.map

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

package/dist/sources/TransitiveSources.d.ts

@@ -0,0 +1,43 @@
+import type { SourceReference } from '../settings/Settings.js';
+import type { RemoteSourceReference } from './SourceCache.js';
+/** A `github:` catalog dependency, pinned to an immutable ref, attributed to its declaring catalog. */
+export interface DeclaredRemoteSource {
+    readonly source: {
+        readonly github: string;
+        readonly ref: string;
+    };
+    /** Display name of the declaring catalog, for warnings and provenance. */
+    readonly declaredBy: string;
+}
+export interface DeclaredSourcesResult {
+    readonly sources: readonly DeclaredRemoteSource[];
+    readonly warnings: readonly string[];
+}
+/** The settings file a catalog payload root may carry: `settings.yml`, else `.agents/settings.yml`. */
+export declare const resolveCatalogSettingsPath: (payloadRoot: string) => string | undefined;
+/**
+ * Reads the `github:` catalog dependencies a cached catalog declares (content, never policy —
+ * OFTR-004.6.2). Transitive sources are deliberately the narrowest safe subset: a `github:`
+ * shorthand pinned to an immutable ref. A `uri:` source, a local `path:` source, a `path:` subpath,
+ * or a mutable ref is skipped with a warning naming the declaring catalog (OFTR-004.6.4,
+ * OFTR-004.6.5). Restricting to `github:` means every transitive fetch during `outfitter sync`
+ * passes through the private-catalog gate and can never select an arbitrary git transport (a `uri:`
+ * could name `ext::<cmd>` or a filesystem path); forbidding `path:` means a declaration can never
+ * escape its fetched checkout. An unreadable or invalid settings file skips the catalog's
+ * declarations without failing resolution (OFTR-004.6.8). (First-party default-catalog bootstrap
+ * fetches its declared closure without that interactive gate — see OFTR-004.6.10.) Broader
+ * transports remain future work under the trust model in #212.
+ */
+export declare const readDeclaredRemoteSources: (payloadRoot: string, checkoutRoot: string, declaredBy: string) => DeclaredSourcesResult;
+export interface TransitiveExpansionInput {
+    /** The directly configured sources, which seed the visited set and the first frontier. */
+    readonly directSources: readonly SourceReference[];
+    /** Maps a remote source to its cached checkout (clone) root, or undefined when it is not cached. */
+    readonly resolveCachedCheckoutRoot: (source: RemoteSourceReference) => string | undefined;
+}
+export interface TransitiveExpansionResult {
+    /** Newly discovered remote sources, breadth-first by depth then declaration order (OFTR-004.6.3). */
+    readonly sources: readonly DeclaredRemoteSource[];
+    readonly warnings: readonly string[];
+}
+export declare const expandTransitiveSources: (input: TransitiveExpansionInput) => TransitiveExpansionResult;

package/dist/sources/TransitiveSources.js

@@ -0,0 +1,177 @@
+// Expands the remote-source closure that cached catalogs declare in their own settings files.
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { createSettingsLoadPlan, loadSettingsFiles } from '../settings/SettingsLoader.js';
+import { encodeRemoteSourceSelection, formatRemoteSourceDisplay, isImmutableRef, isRemoteSource, resolveSourcePayloadRoot, } from './SourceCache.js';
+// True when a filesystem entry exists at the path, *including a dangling symlink*. `existsSync`
+// follows links and reports a dangling one as absent, which would silently drop (rather than warn
+// about, per OFTR-004.6.8) a `settings.yml` committed as a broken symlink.
+const entryExists = (path) => {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The settings file a catalog payload root may carry: `settings.yml`, else `.agents/settings.yml`. */
+export const resolveCatalogSettingsPath = (payloadRoot) => {
+    const rootSettingsPath = join(payloadRoot, 'settings.yml');
+    if (entryExists(rootSettingsPath))
+        return rootSettingsPath;
+    const nestedSettingsPath = join(payloadRoot, '.agents', 'settings.yml');
+    return entryExists(nestedSettingsPath) ? nestedSettingsPath : undefined;
+};
+/** Applies the safe-subset rules to one declared source, yielding a dependency or a skip reason. */
+const classifyDeclaredSource = (declared, declaredBy) => {
+    if (!isRemoteSource(declared)) {
+        return {
+            skip: `Catalog '${declaredBy}' declares local path source '${declared.path}'; only 'github:' shorthands are resolved transitively, so it was skipped.`,
+        };
+    }
+    if (declared.github === undefined) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' as a 'uri:'; only 'github:' shorthands are resolved transitively, so it was skipped.`,
+        };
+    }
+    if (declared.path !== undefined) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' with a 'path:' subpath; transitive 'github:' sources must resolve their whole repository, so it was skipped.`,
+        };
+    }
+    if (declared.ref === undefined || !isImmutableRef(declared.ref)) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' without an immutable ref (a full commit SHA or version tag); it was skipped.`,
+        };
+    }
+    return { source: { github: declared.github, ref: declared.ref } };
+};
+/**
+ * Loads a cached catalog's own settings file, guarding against a hostile `settings.yml` committed as
+ * a symlink to a directory or a file outside the checkout (a `readFileSync` on a directory throws
+ * `EISDIR` and would crash resolution). Returns the parsed sources list, or a skip warning.
+ */
+const loadCatalogSourceList = (payloadRoot, checkoutRoot, declaredBy) => {
+    const settingsPath = resolveCatalogSettingsPath(payloadRoot);
+    if (settingsPath === undefined)
+        return { sources: [] };
+    try {
+        if (!statSync(settingsPath).isFile())
+            throw new Error('settings.yml is not a regular file');
+        // Anchor containment to the *checkout* root (the clone Outfitter created), not the payload root:
+        // a `path:` selecting a symlinked subdirectory would make the payload root itself resolve
+        // outside the clone, so anchoring there would accept an external settings.yml as "contained".
+        const relativeToCheckout = relative(realpathSync(checkoutRoot), realpathSync(settingsPath));
+        // Precise containment: a leading `..` segment (not a filename that merely starts with `..`, such
+        // as a directory named `..catalog`) or an absolute result means the settings escaped the checkout.
+        if (relativeToCheckout === '..' || relativeToCheckout.startsWith(`..${sep}`) || isAbsolute(relativeToCheckout)) {
+            throw new Error('settings.yml resolves outside the checkout');
+        }
+        // Known-accepted TOCTOU: the checkout could be swapped between this stat/realpath check and the
+        // read below. The checkout is a pinned immutable git ref that only Outfitter writes, and racing
+        // local-filesystem writes already imply broader access, so closing this window is not warranted.
+        const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'remote', path: settingsPath }]));
+        if (loaded.issues.length > 0) {
+            return {
+                warning: `Catalog '${declaredBy}' declares invalid settings at '${settingsPath}'; its sources were skipped.`,
+            };
+        }
+        return { sources: loaded.files[0].settings.sources ?? [] };
+    }
+    catch {
+        return {
+            warning: `Catalog '${declaredBy}' has an unreadable settings.yml (not a regular file inside the checkout); its sources were skipped.`,
+        };
+    }
+};
+/**
+ * Reads the `github:` catalog dependencies a cached catalog declares (content, never policy —
+ * OFTR-004.6.2). Transitive sources are deliberately the narrowest safe subset: a `github:`
+ * shorthand pinned to an immutable ref. A `uri:` source, a local `path:` source, a `path:` subpath,
+ * or a mutable ref is skipped with a warning naming the declaring catalog (OFTR-004.6.4,
+ * OFTR-004.6.5). Restricting to `github:` means every transitive fetch during `outfitter sync`
+ * passes through the private-catalog gate and can never select an arbitrary git transport (a `uri:`
+ * could name `ext::<cmd>` or a filesystem path); forbidding `path:` means a declaration can never
+ * escape its fetched checkout. An unreadable or invalid settings file skips the catalog's
+ * declarations without failing resolution (OFTR-004.6.8). (First-party default-catalog bootstrap
+ * fetches its declared closure without that interactive gate — see OFTR-004.6.10.) Broader
+ * transports remain future work under the trust model in #212.
+ */
+export const readDeclaredRemoteSources = (payloadRoot, checkoutRoot, declaredBy) => {
+    const loaded = loadCatalogSourceList(payloadRoot, checkoutRoot, declaredBy);
+    if ('warning' in loaded)
+        return { sources: [], warnings: [loaded.warning] };
+    const sources = [];
+    const warnings = [];
+    for (const declared of loaded.sources) {
+        const classified = classifyDeclaredSource(declared, declaredBy);
+        if ('skip' in classified)
+            warnings.push(classified.skip);
+        else
+            sources.push({ source: classified.source, declaredBy });
+    }
+    return { sources, warnings };
+};
+/**
+ * Walks declared sources breadth-first from the directly configured sources over the local cache.
+ * A source already visited — directly configured or declared by an earlier catalog — is never
+ * expanded again, so dependency cycles terminate (OFTR-004.6.6). An uncached source stays in the
+ * result (the caller reports it) but its own declarations are unknowable until it is synced.
+ */
+// Reads one parent's cached checkout and returns the declarations it contributes. Returns `undefined`
+// (skip this parent) when it is uncached or its `path:` is absolute/escaping — a throw here would
+// otherwise crash resolution; only a directly configured source can carry such a path.
+const declarationsFromParent = (parent, resolveCachedCheckoutRoot) => {
+    const checkoutRoot = resolveCachedCheckoutRoot(parent);
+    if (checkoutRoot === undefined)
+        return undefined;
+    let payloadRoot;
+    try {
+        payloadRoot = resolveSourcePayloadRoot(checkoutRoot, parent);
+    }
+    catch {
+        return undefined;
+    }
+    if (!existsSync(payloadRoot))
+        return undefined;
+    return readDeclaredRemoteSources(payloadRoot, checkoutRoot, formatRemoteSourceDisplay(parent));
+};
+export const expandTransitiveSources = (input) => {
+    const sources = [];
+    const warnings = [];
+    const visited = new Set();
+    // Seed the visited set with each direct source's path-aware identity so a directly configured
+    // subpath source does not suppress a transitive whole-repository source of the same repo+ref, and
+    // so an exact duplicate direct source is expanded only once (OFTR-004.6.6).
+    let frontier = [];
+    for (const direct of input.directSources) {
+        if (!isRemoteSource(direct))
+            continue;
+        const key = encodeRemoteSourceSelection(direct);
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        frontier.push(direct);
+    }
+    while (frontier.length > 0) {
+        const next = [];
+        for (const parent of frontier) {
+            const declared = declarationsFromParent(parent, input.resolveCachedCheckoutRoot);
+            if (declared === undefined)
+                continue;
+            warnings.push(...declared.warnings);
+            for (const entry of declared.sources) {
+                const key = encodeRemoteSourceSelection(entry.source);
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                sources.push(entry);
+                next.push(entry.source);
+            }
+        }
+        frontier = next;
+    }
+    return { sources, warnings };
+};
+//# sourceMappingURL=TransitiveSources.js.map

package/dist/sources/TransitiveSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransitiveSources.js","sourceRoot":"","sources":["../../src/sources/TransitiveSources.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAE1F,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,cAAc,EACd,cAAc,EACd,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAe1B,gGAAgG;AAChG,kGAAkG;AAClG,2EAA2E;AAC3E,MAAM,WAAW,GAAG,CAAC,IAAY,EAAW,EAAE;IAC5C,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,uGAAuG;AACvG,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,WAAmB,EAAsB,EAAE;IACpF,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAC3D,IAAI,WAAW,CAAC,gBAAgB,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAE3D,MAAM,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IACxE,OAAO,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1E,CAAC,CAAC;AAMF,oGAAoG;AACpG,MAAM,sBAAsB,GAAG,CAAC,QAAyB,EAAE,UAAkB,EAAoB,EAAE;IACjG,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,YAAY,UAAU,iCAAiC,QAAQ,CAAC,IAAI,4EAA4E;SACvJ,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO;YACL,IAAI,EAAE,YAAY,UAAU,sBAAsB,yBAAyB,CAAC,QAAQ,CAAC,wFAAwF;SAC9K,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,YAAY,UAAU,sBAAsB,yBAAyB,CAAC,QAAQ,CAAC,gHAAgH;SACtM,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,OAAO;YACL,IAAI,EAAE,YAAY,UAAU,sBAAsB,yBAAyB,CAAC,QAAQ,CAAC,gFAAgF;SACtK,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;AACpE,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,CAC5B,WAAmB,EACnB,YAAoB,EACpB,UAAkB,EAC+D,EAAE;IACnF,MAAM,YAAY,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IAC7D,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAEvD,IAAI,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC5F,iGAAiG;QACjG,0FAA0F;QAC1F,8FAA8F;QAC9F,MAAM,kBAAkB,GAAG,QAAQ,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;QAC5F,iGAAiG;QACjG,mGAAmG;QACnG,IAAI,kBAAkB,KAAK,IAAI,IAAI,kBAAkB,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC/G,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QACD,gGAAgG;QAChG,gGAAgG;QAChG,iGAAiG;QACjG,MAAM,MAAM,GAAG,iBAAiB,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;QACpG,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,YAAY,UAAU,mCAAmC,YAAY,8BAA8B;aAC7G,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,OAAO,EAAE,YAAY,UAAU,sGAAsG;SACtI,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,WAAmB,EACnB,YAAoB,EACpB,UAAkB,EACK,EAAE;IACzB,MAAM,MAAM,GAAG,qBAAqB,CAAC,WAAW,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5E,IAAI,SAAS,IAAI,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAE5E,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,UAAU,GAAG,sBAAsB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAChE,IAAI,MAAM,IAAI,UAAU;YAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;;YACpD,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC,CAAC;AAeF;;;;;GAKG;AACH,sGAAsG;AACtG,kGAAkG;AAClG,uFAAuF;AACvF,MAAM,sBAAsB,GAAG,CAC7B,MAA6B,EAC7B,yBAAgF,EAC7C,EAAE;IACrC,MAAM,YAAY,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEjD,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,wBAAwB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAE/C,OAAO,yBAAyB,CAAC,WAAW,EAAE,YAAY,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAA+B,EAA6B,EAAE;IACpG,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,8FAA8F;IAC9F,kGAAkG;IAClG,4EAA4E;IAC5E,IAAI,QAAQ,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACzC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;YAAE,SAAS;QACtC,MAAM,GAAG,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAA4B,EAAE,CAAC;QAEzC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAC;YACjF,IAAI,QAAQ,KAAK,SAAS;gBAAE,SAAS;YACrC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAEpC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrC,MAAM,GAAG,GAAG,2BAA2B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACtD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACjB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC,CAAC"}

package/dist/system/SystemExtensionHook.d.ts

@@ -0,0 +1,34 @@
+import type { AgentLaunchPlan } from '../projection/Projection.js';
+import type { Harness } from '../settings/Settings.js';
+export interface SystemExtensionHarnessHook {
+    readonly extensions?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+export interface SystemExtensionHook {
+    readonly filePath: string;
+    readonly name: string;
+    readonly harnesses: Partial<Readonly<Record<Harness, SystemExtensionHarnessHook>>>;
+}
+export interface SystemExtensionHookSource {
+    readonly directory: string;
+    readonly stamp: string;
+}
+export interface LoadedSystemExtensionHooks {
+    readonly hooks: readonly SystemExtensionHook[];
+    readonly source?: SystemExtensionHookSource;
+}
+export interface AttachedSystemExtensionHooks {
+    readonly launch: AgentLaunchPlan;
+    readonly warnings: readonly string[];
+}
+export interface SystemExtensionHookDiscoveryInput {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+export declare const resolveSystemExtensionHookSource: (input?: SystemExtensionHookDiscoveryInput) => SystemExtensionHookSource | undefined;
+export declare const readSystemExtensionHooks: (input?: SystemExtensionHookDiscoveryInput) => LoadedSystemExtensionHooks;
+/**
+ * Prepends every system Pi extension after projection, including for RPC/print launches. Hook env
+ * stays beneath the projected plan env so it cannot replace Outfitter's runtime/session paths.
+ */
+export declare const attachSystemExtensionHooks: (plan: AgentLaunchPlan, loaded?: LoadedSystemExtensionHooks) => AttachedSystemExtensionHooks;