aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
75 lines • 3.57 kB
TypeScript
/**
* Shadow Resolver
*
* Implements the override / shadow-resolution policy from
* `.aiwg/architecture/adr-override-shadow-policy.md` (#1041) for project-local
* artifact bundles deployed via `aiwg use` / `aiwg refresh`.
*
* Resolves the seven cases from ADR §4:
*
* 1. No collision — deploy normally
* 2. Non-safety-critical shadow — deploy + warn
* 3. Safety-critical shadow with `overrides:` declaration — deploy + prominent warn
* 4. Safety-critical shadow without `overrides:` — REFUSE
* 5. Phantom override (declared override has no upstream match) — REFUSE
* 6. Two project-local bundles export the same id — REFUSE both
* 7. git-installed source collides with project-local — same as 2/3/4 against cache
*
* Inputs: the project-local bundles (from `discoverProjectLocalBundles`) and
* an upstream registry (from `buildUpstreamRegistry`). Outputs a per-artifact
* verdict that the deployment pipeline consumes to decide what to write to
* provider paths.
*
* @implements #1036
*/
import type { ProjectLocalBundle } from './project-local-discovery.js';
import type { UpstreamArtifact, UpstreamArtifactType, UpstreamRegistry } from './upstream-registry.js';
export type ShadowVerdict = 'deploy' | 'deploy-with-warning' | 'deploy-acknowledged' | 'refuse-unsafe' | 'refuse-phantom' | 'refuse-duplicate';
export interface ShadowResolution {
/** Project-local bundle the artifact belongs to. */
bundleId: string;
bundleLocalPath: string;
/** Artifact within the bundle. */
artifactId: string;
artifactType: UpstreamArtifactType;
artifactSourcePath: string;
/** Upstream artifact being shadowed (when applicable). */
upstream?: UpstreamArtifact;
verdict: ShadowVerdict;
/** Operator-visible message for warning / error output. */
message: string;
/** True for verdicts that block deployment of this artifact. */
blocking: boolean;
/** True for the prominent (multi-line, color-in-TTY) safety-critical warning. */
prominent: boolean;
}
export interface ResolveOptions {
/** Strict mode: phantom overrides also block bundle deployment.
* Defaults to true (matches ADR §4 case 5). */
strictPhantomOverrides?: boolean;
}
export interface ResolveResult {
resolutions: ShadowResolution[];
/** Bundle ids that have at least one blocking resolution and should be
* skipped wholesale (case 6 — duplicate id refuses both). */
blockedBundleIds: Set<string>;
/** Convenience filters. */
shadows: ShadowResolution[];
}
interface BundleArtifact {
id: string;
type: UpstreamArtifactType;
sourcePath: string;
}
/** Enumerate the artifacts a project-local bundle would deploy by walking its
* source `agents/`, `skills/`, `rules/`, `commands/` subdirs — same pattern as
* `deployOneProjectLocalBundle` and `countBundleSourceArtifacts` in use.ts. */
export declare function enumerateBundleArtifacts(bundlePath: string): Promise<BundleArtifact[]>;
/** Resolve overrides + shadows for a set of project-local bundles against an
* upstream registry. Pure function — no filesystem side effects beyond reading
* the bundle artifact files for id extraction. */
export declare function resolveShadows(bundles: ProjectLocalBundle[], upstream: UpstreamRegistry, options?: ResolveOptions): Promise<ResolveResult>;
/** Format a multi-resolution summary suitable for stderr or doctor output. */
export declare function formatShadowReport(result: ResolveResult): string;
export {};
//# sourceMappingURL=shadow-resolver.d.ts.map