@vpxa/aikit 0.1.59 → 0.1.60

package/packages/flows/dist/index.d.ts

@@ -1,13 +1,346 @@
-import { ContentTransformFn, FlowFormat, FlowFormatAdapter, FlowManifest, FlowParseOptions, FlowRegistry, FlowRegistryEntry, FlowResult, FlowSourceType, FlowState, FlowStatus, FlowStep, StepAction } from "./types.js";
-import { ClaudePluginAdapter } from "./adapters/claude-plugin.js";
-import { CopilotAdapter } from "./adapters/copilot.js";
-import { NativeAdapter } from "./adapters/native.js";
-import { OpenSpecAdapter } from "./adapters/openspec.js";
-import { BuiltinFlow, getBuiltinFlows } from "./builtins.js";
-import { FoundationIntegration } from "./foundation.js";
-import { GitInstaller } from "./git.js";
-import { FlowLoader } from "./loader.js";
-import { FlowRegistryManager } from "./registry.js";
-import { FlowStateMachine } from "./state-machine.js";
-import { SymlinkManager } from "./symlinks.js";
+//#region packages/flows/src/types.d.ts
+/**
+ * @aikit/flows — Type definitions for the pluggable flow system.
+ */
+/** A single step in a flow */
+interface FlowStep {
+  /** Unique step identifier within the flow (e.g., "spec", "plan", "execute") */
+  id: string;
+  /** Human-readable step name */
+  name: string;
+  /** Relative path to the step's instruction file */
+  instruction: string;
+  /** Artifact filenames this step produces */
+  produces: string[];
+  /** Step IDs this step depends on (must be completed first) */
+  requires: string[];
+  /** Agent files specific to this step (relative paths) */
+  agents: string[];
+  /** Step description */
+  description: string;
+}
+/** Flow manifest — the flow.json schema */
+interface FlowManifest {
+  /** Flow name (unique identifier) */
+  name: string;
+  /** Semantic version */
+  version: string;
+  /** Human-readable description */
+  description: string;
+  /** Author name or organization */
+  author?: string;
+  /** Ordered list of steps */
+  steps: FlowStep[];
+  /** Flow-level agent files (relative paths) */
+  agents: string[];
+  /** Directory for artifacts (default: ".spec") */
+  artifacts_dir: string;
+  /** External dependencies to install at flow-add time */
+  install: string[];
+}
+/** Source type for flow installation */
+type FlowSourceType = 'builtin' | 'git' | 'local' | 'npm-global' | 'claude-plugin';
+/** Detected format of the flow source */
+type FlowFormat = 'native' | 'claude-plugin' | 'copilot' | 'openspec';
+type ContentTransformFn = (request: {
+  content: string;
+  sourceFormat: FlowFormat;
+  stepName: string;
+  metadata?: Record<string, unknown>;
+}) => Promise<string>;
+/** Registry entry for an installed flow */
+interface FlowRegistryEntry {
+  /** Flow name */
+  name: string;
+  /** Flow version */
+  version: string;
+  /** Original source (URL, path, or "builtin") */
+  source: string;
+  /** How the flow was installed */
+  sourceType: FlowSourceType;
+  /** Absolute path where flow files are stored */
+  installPath: string;
+  /** Detected source format */
+  format: FlowFormat;
+  /** ISO timestamp when registered */
+  registeredAt: string;
+  /** ISO timestamp of last update */
+  updatedAt: string;
+  /** Parsed manifest (cached) */
+  manifest: FlowManifest;
+  /** Git commit SHA of the installed version (git sources only) */
+  commitSha?: string;
+}
+/** The flow registry file structure */
+interface FlowRegistry {
+  /** Schema version */
+  version: 1;
+  /** Map of flow name → registry entry */
+  flows: Record<string, FlowRegistryEntry>;
+}
+/** Flow execution state */
+type FlowStatus = 'idle' | 'active' | 'completed';
+/** Active flow state (persisted to state.json) */
+interface FlowState {
+  /** Which flow is active (name from registry) */
+  flow: string;
+  /** Current status */
+  status: FlowStatus;
+  /** Current step ID (null if not started) */
+  currentStep: string | null;
+  /** Completed step IDs in order */
+  completedSteps: string[];
+  /** Skipped step IDs */
+  skippedSteps: string[];
+  /** Map of artifact name → file path */
+  artifacts: Record<string, string>;
+  /** ISO timestamp when flow was started */
+  startedAt: string;
+  /** ISO timestamp of last state change */
+  updatedAt: string;
+}
+/** Step action for state machine transitions */
+type StepAction = 'next' | 'skip' | 'redo';
+/** Options passed to format adapter parse */
+interface FlowParseOptions {
+  /** When true, force-refresh supporting assets (e.g. on update) */
+  forceAssetSync?: boolean;
+  /** Optional content transformer for converting foreign step content to native README.md */
+  transform?: ContentTransformFn;
+}
+/** Format adapter interface — converts external formats to FlowManifest */
+interface FlowFormatAdapter {
+  /** Format name */
+  readonly format: FlowFormat;
+  /** Check if a directory matches this format */
+  detect(sourceDir: string): boolean;
+  /** Parse the source directory into a FlowManifest */
+  parse(sourceDir: string, options?: FlowParseOptions): Promise<FlowManifest>;
+}
+/** Result of a flow operation */
+interface FlowResult<T = void> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+//#endregion
+//#region packages/flows/src/adapters/claude-plugin.d.ts
+declare class ClaudePluginAdapter implements FlowFormatAdapter {
+  readonly format: "claude-plugin";
+  detect(sourceDir: string): boolean;
+  parse(sourceDir: string, options?: FlowParseOptions): Promise<FlowManifest>;
+  private readPluginJson;
+  private readString;
+  private discoverSteps;
+  private readStep;
+  /**
+   * Copy supporting subdirectories (references/, assets/, scripts/) from
+   * skills/<step>/ to steps/<step>/ so that relative paths inside the
+   * step README.md resolve correctly at runtime.
+   *
+   * When `force` is true, existing copies are replaced (used during updates).
+   */
+  private syncStepAssets;
+  private materializeNativeSteps;
+  private buildStepReadme;
+  private discoverAgents;
+}
+//#endregion
+//#region packages/flows/src/adapters/copilot.d.ts
+declare class CopilotAdapter implements FlowFormatAdapter {
+  readonly format: "copilot";
+  detect(sourceDir: string): boolean;
+  parse(sourceDir: string, options?: FlowParseOptions): Promise<FlowManifest>;
+  private getStepId;
+  private materializeSteps;
+}
+//#endregion
+//#region packages/flows/src/adapters/native.d.ts
+declare class NativeAdapter implements FlowFormatAdapter {
+  readonly format: "native";
+  detect(sourceDir: string): boolean;
+  parse(sourceDir: string): Promise<FlowManifest>;
+}
+//#endregion
+//#region packages/flows/src/adapters/openspec.d.ts
+/**
+ * OpenSpec adapter — detects repos that follow the OpenSpec workflow
+ * (https://github.com/Fission-AI/OpenSpec) and converts them to FlowManifest.
+ *
+ * Detection marker: `openspec/config.yaml` in the source directory.
+ *
+ * Flow steps are derived from the active OpenSpec schema.yaml.
+ */
+declare class OpenSpecAdapter implements FlowFormatAdapter {
+  readonly format: "openspec";
+  detect(sourceDir: string): boolean;
+  parse(sourceDir: string, options?: FlowParseOptions): Promise<FlowManifest>;
+  /**
+   * Read metadata from package.json if available, otherwise use defaults
+   * derived from the openspec config.
+   */
+  private readMeta;
+  private readConfigSchema;
+  private resolveSchemaDir;
+  private parseSchemaArtifacts;
+  private loadSchema;
+  private discoverSchemaFromDirectory;
+  private collectMarkdownFiles;
+  private hasFileRecursive;
+  private findSchemaYaml;
+  private toStepIdFromMarkdown;
+  private buildStepsFromSchema;
+  private materializeSteps;
+  private resolveInstructionContent;
+  private normalizeArtifact;
+  private normalizeApply;
+  private readString;
+  private readStringArray;
+  private humanizeStepName;
+}
+//#endregion
+//#region packages/flows/src/builtins.d.ts
+interface BuiltinFlow {
+  /** Flow manifest */
+  manifest: FlowManifest;
+  /** Relative path within the monorepo where scaffold files live */
+  scaffoldDir: string;
+}
+/**
+ * Returns all built-in flow definitions bundled with @aikit/flows.
+ * These flows are always available, even without installation via `flow add`.
+ */
+declare function getBuiltinFlows(): BuiltinFlow[];
+//#endregion
+//#region packages/flows/src/foundation.d.ts
+declare class FoundationIntegration {
+  /**
+   * Inject foundation preamble into a file.
+   * Replaces existing preamble if present, otherwise prepends.
+   */
+  injectPreamble(filePath: string, manifest: FlowManifest): void;
+  /**
+   * Remove foundation preamble from a file.
+   */
+  removePreamble(filePath: string): void;
+  /**
+   * Get list of IDE instruction files to inject preamble into.
+   */
+  getTargetFiles(workspaceRoot: string): string[];
+}
+//#endregion
+//#region packages/flows/src/git.d.ts
+declare class GitInstaller {
+  private readonly flowsDir;
+  constructor(flowsDir: string);
+  /**
+   * Clone a git repo into the flows directory.
+   * On auth failure, if GCM is available, retries interactively so the
+   * credential manager can open a browser / device-code flow.
+   * Returns the local install path.
+   */
+  clone(repoUrl: string, token?: string): FlowResult<string>;
+  /**
+   * Update an existing cloned flow repo.
+   */
+  update(installPath: string): FlowResult;
+  /**
+   * Copy a local directory as a flow source.
+   */
+  copyLocal(sourcePath: string, name: string): FlowResult<string>;
+  /**
+   * Remove installed flow files.
+   */
+  remove(installPath: string): FlowResult;
+  /**
+   * Run install dependencies for a flow.
+   * Processes the `install[]` field from flow.json.
+   */
+  runInstallDeps(installEntries: string[]): FlowResult;
+  /**
+   * Get the current HEAD commit SHA for a local git repo.
+   */
+  getLocalCommit(installPath: string): string | null;
+  /**
+   * Get the latest commit SHA on the remote default branch.
+   * Uses `git ls-remote` so it doesn't modify the working tree.
+   */
+  getRemoteCommit(installPath: string): string | null;
+  /**
+   * Check whether the remote has commits newer than the local HEAD.
+   */
+  hasUpdates(installPath: string): FlowResult<{
+    localCommit: string;
+    remoteCommit: string;
+    hasUpdates: boolean;
+  }>;
+  /** Extract repo name from git URL */
+  private repoNameFromUrl;
+  private ensureFlowsDir;
+}
+//#endregion
+//#region packages/flows/src/loader.d.ts
+declare class FlowLoader {
+  load(sourceDir: string, options?: FlowParseOptions): Promise<FlowResult<{
+    manifest: FlowManifest;
+    format: FlowFormat;
+  }>>;
+  loadWithFormat(sourceDir: string, format: FlowFormat, options?: FlowParseOptions): Promise<FlowResult<FlowManifest>>;
+  validate(manifest: FlowManifest): FlowResult;
+}
+//#endregion
+//#region packages/flows/src/registry.d.ts
+declare class FlowRegistryManager {
+  private readonly registryPath;
+  constructor(registryPath: string);
+  /** Load registry from disk, or create empty if missing */
+  load(): FlowRegistry;
+  /** Save registry to disk */
+  save(registry: FlowRegistry): void;
+  /** Register a new flow or update an existing one */
+  register(entry: FlowRegistryEntry): FlowResult;
+  /** Remove a flow from the registry */
+  unregister(name: string): FlowResult;
+  /** Get a specific flow entry (checks disk registry first, then builtins) */
+  get(name: string): FlowRegistryEntry | null;
+  /** List all registered flows (disk + builtins, disk overrides builtins) */
+  list(): FlowRegistryEntry[];
+  /** Check if a flow is registered (disk or builtin) */
+  has(name: string): boolean;
+}
+//#endregion
+//#region packages/flows/src/state-machine.d.ts
+declare class FlowStateMachine {
+  private readonly statePath;
+  constructor(statePath: string);
+  /** Load active flow state from disk, or null if no active flow */
+  load(): FlowState | null;
+  /** Save state to disk */
+  private save;
+  /** Start a new flow */
+  start(flowName: string, manifest: FlowManifest): FlowResult<FlowState>;
+  /** Advance the flow: next, skip, or redo current step */
+  step(action: StepAction, manifest: FlowManifest): FlowResult<FlowState>;
+  /** Get current flow status */
+  getStatus(): FlowResult<FlowState>;
+  /** Reset flow state (clear active flow) */
+  reset(): FlowResult;
+  /** Record an artifact produced by a step */
+  recordArtifact(name: string, path: string): FlowResult;
+}
+//#endregion
+//#region packages/flows/src/symlinks.d.ts
+declare class SymlinkManager {
+  /**
+   * Create agent symlinks for a flow in the workspace.
+   */
+  createSymlinks(workspaceRoot: string, flowName: string, flowInstallPath: string, manifest: FlowManifest): void;
+  /**
+   * Remove agent symlinks for a flow.
+   */
+  removeSymlinks(workspaceRoot: string, flowName: string): void;
+  private getTargets;
+  private getAgentStem;
+}
+//#endregion
 export { type BuiltinFlow, ClaudePluginAdapter, type ContentTransformFn, CopilotAdapter, type FlowFormat, type FlowFormatAdapter, FlowLoader, type FlowManifest, type FlowParseOptions, type FlowRegistry, type FlowRegistryEntry, FlowRegistryManager, type FlowResult, type FlowSourceType, type FlowState, FlowStateMachine, type FlowStatus, type FlowStep, FoundationIntegration, GitInstaller, NativeAdapter, OpenSpecAdapter, type StepAction, SymlinkManager, getBuiltinFlows };

package/packages/flows/dist/index.js

@@ -1 +1,15 @@
-import{getBuiltinFlows as e}from"./builtins.js";import{FoundationIntegration as t}from"./foundation.js";import{GitInstaller as n}from"./git.js";import{ClaudePluginAdapter as r}from"./adapters/claude-plugin.js";import{CopilotAdapter as i}from"./adapters/copilot.js";import{NativeAdapter as a}from"./adapters/native.js";import{OpenSpecAdapter as o}from"./adapters/openspec.js";import{FlowLoader as s}from"./loader.js";import{FlowRegistryManager as c}from"./registry.js";import{FlowStateMachine as l}from"./state-machine.js";import{SymlinkManager as u}from"./symlinks.js";export{r as ClaudePluginAdapter,i as CopilotAdapter,s as FlowLoader,c as FlowRegistryManager,l as FlowStateMachine,t as FoundationIntegration,n as GitInstaller,a as NativeAdapter,o as OpenSpecAdapter,u as SymlinkManager,e as getBuiltinFlows};
+import{copyFileSync as e,cpSync as t,existsSync as n,mkdirSync as r,readFileSync as i,readdirSync as a,rmSync as o,rmdirSync as s,symlinkSync as c,unlinkSync as l,writeFileSync as u}from"node:fs";import{basename as d,dirname as f,join as p,relative as m}from"node:path";import{execSync as h,spawnSync as g}from"node:child_process";import{parse as _}from"yaml";import{tmpdir as v}from"node:os";const y=[`spec`,`plan`,`task`,`execute`,`verify`];function b(e){let t=e.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);if(!t)return{data:{},body:e};let n={};for(let e of t[1].split(/\r?\n/)){let t=e.indexOf(`:`);t>0&&(n[e.slice(0,t).trim()]=e.slice(t+1).trim().replace(/^["']|["']$/g,``))}return{data:n,body:t[2]}}function x(e){return e.split(/[-_]/g).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(` `)}function S(e){let t=y.indexOf(e);return t===-1?1/0:t}var C=class{format=`claude-plugin`;detect(e){return n(p(e,`.claude-plugin`,`plugin.json`))}async parse(e,t){let n=this.readPluginJson(e),r=this.discoverSteps(e);await this.materializeNativeSteps(e,r,t);let i=this.discoverAgents(e),a=r.map(({step:e})=>e);return{name:this.readString(n.name)??d(e),version:this.readString(n.version)??`1.0.0`,description:this.readString(n.description)??``,author:this.readString(n.author),steps:a,agents:i,artifacts_dir:`.spec`,install:[]}}readPluginJson(e){let t=p(e,`.claude-plugin`,`plugin.json`);return JSON.parse(i(t,`utf-8`))}readString(e){return typeof e==`string`?e:void 0}discoverSteps(e){let t=p(e,`skills`);if(!n(t))return[];let r=a(t,{withFileTypes:!0}).filter(e=>e.isDirectory()).map(e=>e.name).map(t=>this.readStep(e,t)).filter(e=>e!==null).sort((e,t)=>{let n=Number(e.metadata.order),r=Number(t.metadata.order),i=Number.isFinite(n),a=Number.isFinite(r);if(i&&a)return n-r;if(i)return-1;if(a)return 1;let o=S(e.step.id),s=S(t.step.id);return o===s?e.step.id.localeCompare(t.step.id):o-s});return r.map((e,t)=>({...e,step:{...e.step,requires:t>0?[r[t-1].step.id]:[]}}))}readStep(e,t){let r=p(e,`skills`,t,`SKILL.md`);if(!n(r))return null;let a=i(r,`utf-8`),{data:o,body:s}=b(a),c=o.name||x(t),l=o.description||`${c} step`;return{step:{id:t,name:c,instruction:`steps/${t}/README.md`,produces:[`${t}.md`],requires:[],agents:[],description:l},metadata:o,content:a,body:s}}syncStepAssets(e,r,i){let a=[`references`,`assets`,`scripts`];for(let s of r)for(let r of a){let a=p(e,`skills`,s.id,r),c=p(e,`steps`,s.id,r);if(n(a)){if(n(c)){if(!i)continue;o(c,{recursive:!0,force:!0})}t(a,c,{recursive:!0})}}}async materializeNativeSteps(e,t,n){for(let i of t){let t=p(e,`steps`,i.step.id);r(t,{recursive:!0});let a=n?.transform?await n.transform({content:i.content,sourceFormat:`claude-plugin`,stepName:i.step.id,metadata:i.metadata}):this.buildStepReadme(i.step.name,i.step.description,i.body);u(p(t,`README.md`),a,`utf-8`)}this.syncStepAssets(e,t.map(({step:e})=>e),n?.forceAssetSync)}buildStepReadme(e,t,n){return[`# ${e}`,``,t,``,`---`,``,n.trim()].join(`
+`).trimEnd().concat(`
+`)}discoverAgents(e){let t=p(e,`agents`);return n(t)?a(t,{withFileTypes:!0}).filter(e=>e.isFile()&&e.name.endsWith(`.md`)).map(e=>`agents/${e.name}`):[]}},w=class{format=`copilot`;detect(e){return n(p(e,`.github`,`agents`))}async parse(e,t){let n=a(p(e,`.github`,`agents`),{withFileTypes:!0}).filter(e=>e.isFile()&&e.name.endsWith(`.md`)).map(e=>`.github/agents/${e.name}`),r=n.map(e=>this.getStepId(e)),i=n.map((e,t)=>{let n=r[t];return{id:n,name:n.charAt(0).toUpperCase()+n.slice(1),instruction:`steps/${n}/README.md`,produces:[`${n}.md`],requires:t>0?[r[t-1]]:[],agents:[e],description:`${n} agent step`}});return await this.materializeSteps(e,i,t),{name:d(e),version:`1.0.0`,description:`Copilot agents flow from ${d(e)}`,steps:i,agents:n,artifacts_dir:`.spec`,install:[]}}getStepId(e){return d(e,`.md`).toLowerCase().replace(/\.agent$/,``)}async materializeSteps(e,t,n){for(let a of t){let t=a.agents[0];if(!t)continue;let o=i(p(e,t),`utf-8`),s=p(e,`steps`,a.id),c=p(s,`README.md`);r(s,{recursive:!0}),u(c,n?.transform?await n.transform({content:o,sourceFormat:`copilot`,stepName:a.id,metadata:{sourcePath:t,displayName:a.name}}):`# ${a.name}\n\n${o}`,`utf-8`)}}},T=class{format=`native`;detect(e){return n(p(e,`flow.json`))}async parse(e){let t=i(p(e,`flow.json`),`utf-8`);return JSON.parse(t)}},E=class{format=`openspec`;detect(e){return!!(n(p(e,`openspec`,`config.yaml`))||n(p(e,`schemas`))&&this.findSchemaYaml(e))}async parse(e,t){let n=this.readMeta(e),r=this.loadSchema(e),i=this.buildStepsFromSchema(r);return await this.materializeSteps(e,i,r,t),{name:n.name,version:n.version,description:r.description??n.description,author:n.author,steps:i,agents:[],artifacts_dir:`openspec`,install:[]}}readMeta(e){let t=p(e,`package.json`);if(n(t))try{let n=JSON.parse(i(t,`utf-8`));return{name:n.name??d(e),version:n.version??`0.1.0`,description:n.description??`OpenSpec flow`,author:n.author}}catch{}return{name:d(e),version:`0.1.0`,description:`OpenSpec flow`}}readConfigSchema(e){let t=p(e,`openspec`,`config.yaml`);if(!n(t))return`spec-driven`;try{let e=_(i(t,`utf-8`));return typeof e?.schema==`string`&&e.schema.trim().length>0?e.schema:`spec-driven`}catch{return`spec-driven`}}resolveSchemaDir(e){let t=this.readConfigSchema(e),r=p(e,`openspec`,`schemas`,t);if(n(p(r,`schema.yaml`)))return r;let i=p(e,`schemas`,t);if(n(p(i,`schema.yaml`)))return i;try{let e=p(h(`npm root -g`,{encoding:`utf-8`,timeout:5e3,stdio:[`ignore`,`pipe`,`ignore`]}).trim(),`@fission-ai`,`openspec`,`schemas`,t);if(n(p(e,`schema.yaml`)))return e}catch{}return null}parseSchemaArtifacts(e){try{let t=_(e);if(!t||!Array.isArray(t.artifacts))return null;let n=t.artifacts.map(e=>this.normalizeArtifact(e)).filter(e=>e!==null);return n.length===0?null:{name:typeof t.name==`string`&&t.name.trim().length>0?t.name:this.readString(t.schema)??`spec-driven`,version:typeof t.version==`number`?t.version:1,description:this.readString(t.description),artifacts:n,apply:this.normalizeApply(t.apply)}}catch{return null}}loadSchema(e){let t=this.resolveSchemaDir(e);if(t){let e=p(t,`schema.yaml`);try{let t=i(e,`utf-8`),n=this.parseSchemaArtifacts(t);if(n)return n}catch{}}return this.discoverSchemaFromDirectory(e)}discoverSchemaFromDirectory(e){let t=[p(e,`openspec`,`schemas`),p(e,`schemas`)];for(let e of t)if(n(e))try{let t=a(e,{withFileTypes:!0}).filter(e=>e.isDirectory());for(let r of t){let t=p(e,r.name,`schema.yaml`);if(n(t))try{let e=this.parseSchemaArtifacts(i(t,`utf-8`));if(e)return e}catch{}}}catch{}let r=[],o=p(e,`openspec`),s=[],c=this.collectMarkdownFiles(o);for(let e of c){let t=m(o,e).replace(/\\/g,`/`),n=this.toStepIdFromMarkdown(t);!n||s.includes(n)||(r.push({id:n,generates:t,description:`${this.humanizeStepName(n)} phase`,template:d(e),requires:s.length>0?[s[s.length-1]]:[]}),s.push(n))}return{name:this.readConfigSchema(e),version:1,artifacts:r}}collectMarkdownFiles(e){if(!n(e))return[];let t=[];try{let n=a(e,{withFileTypes:!0}).sort((e,t)=>e.name.localeCompare(t.name));for(let r of n){let n=p(e,r.name);if(r.isFile()&&r.name.toLowerCase().endsWith(`.md`)){t.push(n);continue}r.isDirectory()&&t.push(...this.collectMarkdownFiles(n))}}catch{}return t}hasFileRecursive(e,t){if(!n(e))return!1;try{let n=a(e,{withFileTypes:!0});for(let r of n)if(r.isFile()&&r.name===t||r.isDirectory()&&this.hasFileRecursive(p(e,r.name),t))return!0}catch{}return!1}findSchemaYaml(e){let t=p(e,`schemas`);if(!n(t))return!1;try{return a(t,{withFileTypes:!0}).filter(e=>e.isDirectory()).some(e=>n(p(t,e.name,`schema.yaml`)))}catch{return!1}}toStepIdFromMarkdown(e){let t=e.replace(/\\/g,`/`).split(`/`).filter(Boolean);if(t.length===0)return null;let n=(t[t.length-1]??``).replace(/\.md$/i,``);return(n.toLowerCase()===`readme`&&t.length>1?t[t.length-2]:n).toLowerCase().replace(/[^a-z0-9]+/g,`-`).replace(/^-+|-+$/g,``)||null}buildStepsFromSchema(e){let t=e.artifacts.map(e=>({id:e.id,name:this.humanizeStepName(e.id),instruction:`steps/${e.id}/README.md`,produces:e.generates?[e.generates]:[],requires:e.requires,agents:[],description:e.description}));return e.apply&&t.push({id:`apply`,name:`Apply`,instruction:`steps/apply/README.md`,produces:[],requires:e.apply.requires,agents:[],description:`Implement the tasks, writing code and tests according to the design`}),t}async materializeSteps(e,t,i,a){let o=this.resolveSchemaDir(e),s=new Map(i.artifacts.map(e=>[e.id,e]));for(let c of t){let t=p(e,`steps`,c.id),l=p(t,`README.md`);r(t,{recursive:!0});let d=this.resolveInstructionContent(o,c.id,s.get(c.id),i.apply);if(!d){n(l)||u(l,`# ${c.name}\n\n${c.description}\n`,`utf-8`);continue}u(l,a?.transform?await a.transform({content:d,sourceFormat:`openspec`,stepName:c.id,metadata:{schemaName:i.name,displayName:c.name,description:c.description,produces:c.produces,requires:c.requires}}):`# ${c.name}\n\n${d}`,`utf-8`)}}resolveInstructionContent(e,t,r,a){if(t===`apply`&&a?.instruction)return a.instruction;if(!r)return null;if(r.instruction)return r.instruction;if(e&&r.template){let t=p(e,`templates`,r.template);if(n(t))try{return i(t,`utf-8`)}catch{}}return r.description||null}normalizeArtifact(e){if(!e||typeof e!=`object`)return null;let t=e,n=this.readString(t.id),r=this.readString(t.generates);return!n||!r?null:{id:n,generates:r,description:this.readString(t.description)??`${this.humanizeStepName(n)} phase`,template:this.readString(t.template)??``,instruction:this.readString(t.instruction),requires:this.readStringArray(t.requires)}}normalizeApply(e){if(!e||typeof e!=`object`)return;let t=e;return{requires:this.readStringArray(t.requires),tracks:this.readString(t.tracks)??null,instruction:this.readString(t.instruction)}}readString(e){return typeof e==`string`&&e.trim().length>0?e:void 0}readStringArray(e){return Array.isArray(e)?e.filter(e=>typeof e==`string`&&e.length>0):[]}humanizeStepName(e){return e.split(/[-_]/g).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(` `)}};const D={name:`aikit:basic`,version:`0.1.0`,description:`Quick development flow for bug fixes, small features, and refactoring`,steps:[{id:`design`,name:`Design Gate`,instruction:`steps/design/README.md`,produces:[`design-decisions.md`],requires:[],agents:[`Researcher-Alpha`,`Researcher-Beta`,`Researcher-Gamma`,`Researcher-Delta`],description:`Evaluate task type, run brainstorming for features, FORGE classification. Auto-skips for bug fixes and refactors.`},{id:`assess`,name:`Assessment`,instruction:`steps/assess/README.md`,produces:[`assessment.md`],requires:[`design-decisions.md`],agents:[`Explorer`,`Researcher-Alpha`],description:`Understand scope, analyze codebase, identify approach`},{id:`implement`,name:`Implementation`,instruction:`steps/implement/README.md`,produces:[`progress.md`],requires:[`assessment.md`],agents:[`Implementer`,`Frontend`],description:`Write code following the assessment plan`},{id:`verify`,name:`Verification`,instruction:`steps/verify/README.md`,produces:[`verify-report.md`],requires:[`progress.md`],agents:[`Code-Reviewer-Alpha`,`Security`],description:`Review code, run tests, validate changes`}],agents:[],artifacts_dir:`.spec`,install:[]},O={name:`aikit:advanced`,version:`0.1.0`,description:`Full development flow for new features, API design, and architecture changes`,steps:[{id:`design`,name:`Design Gate`,instruction:`steps/design/README.md`,produces:[`design-decisions.md`],requires:[],agents:[`Researcher-Alpha`,`Researcher-Beta`,`Researcher-Gamma`,`Researcher-Delta`],description:`Full brainstorming, FORGE classification, decision protocol with parallel research. ADR for critical-tier tasks.`},{id:`spec`,name:`Specification`,instruction:`steps/spec/README.md`,produces:[`spec.md`],requires:[`design-decisions.md`],agents:[`Researcher-Alpha`],description:`Elicit requirements, clarify scope, define acceptance criteria`},{id:`plan`,name:`Planning`,instruction:`steps/plan/README.md`,produces:[`plan.md`],requires:[`spec.md`],agents:[`Planner`,`Explorer`],description:`Analyze codebase, design architecture, create implementation plan`},{id:`task`,name:`Task Breakdown`,instruction:`steps/task/README.md`,produces:[`tasks.md`],requires:[`plan.md`],agents:[`Planner`,`Architect-Reviewer-Alpha`],description:`Break plan into ordered implementation tasks with dependencies`},{id:`execute`,name:`Execution`,instruction:`steps/execute/README.md`,produces:[`progress.md`],requires:[`tasks.md`],agents:[`Orchestrator`,`Implementer`,`Frontend`,`Refactor`],description:`Implement all tasks, write code, write tests`},{id:`verify`,name:`Verification`,instruction:`steps/verify/README.md`,produces:[`verify-report.md`],requires:[`progress.md`],agents:[`Code-Reviewer-Alpha`,`Code-Reviewer-Beta`,`Architect-Reviewer-Alpha`,`Architect-Reviewer-Beta`,`Security`],description:`Dual code review, architecture review, security review, test validation`}],agents:[],artifacts_dir:`.spec`,install:[]};function k(){return[{manifest:D,scaffoldDir:`scaffold/flows/aikit-basic`},{manifest:O,scaffoldDir:`scaffold/flows/aikit-advanced`}]}const A=`<!-- aikit foundation context -->`,j=`<!-- end foundation context -->`;function M(e){let t=e.artifacts_dir||`.spec`;return`${A}
+You are operating within the @vpxa/aikit framework.
+- Use aikit MCP tools for all search, analysis, and memory operations
+- Follow agents defined in AGENTS.md for delegation
+- Use built-in skills (brainstorming, requirements-clarity, etc.) as needed
+- Track state via the flow state machine (flow_status, flow_step)
+- Active flow: ${e.name} v${e.version}
+- Artifacts go in: ${t}/${e.name}/
+${j}`}var N=class{injectPreamble(e,t){let r=M(t);if(!n(e)){u(e,`${r}\n`,`utf-8`);return}let a=i(e,`utf-8`),o=a.indexOf(A),s=a.indexOf(j);if(o!==-1&&s!==-1){u(e,`${a.slice(0,o)}${r}${a.slice(s+31)}`,`utf-8`);return}u(e,`${r}\n\n${a}`,`utf-8`)}removePreamble(e){if(!n(e))return;let t=i(e,`utf-8`),r=t.indexOf(A),a=t.indexOf(j);r===-1||a===-1||u(e,(t.slice(0,r)+t.slice(a+31)).replace(/^\n+/,``).replace(/\n{3,}/g,`
+
+`),`utf-8`)}getTargetFiles(e){let t=[],r=p(e,`.github`,`copilot-instructions.md`);n(r)&&t.push(r);let i=p(e,`CLAUDE.md`);n(i)&&t.push(i);let a=p(e,`AGENTS.md`);return n(a)&&t.push(a),t}};function P(e){if(!e||typeof e!=`object`||!(`stderr`in e))return``;let t=e.stderr;return Buffer.isBuffer(t)?t.toString().trim():typeof t==`string`?t.trim():``}function F(e){try{return new URL(e).hostname}catch{}return e.match(/^[^@]+@([^:]+):/)?.[1]??`<host>`}function I(e,t,n){let r=[`Git operation failed for: ${e}`],i=F(e),a=t.includes(`ETIMEDOUT`)||t.includes(`SIGTERM`)||t.toLowerCase().includes(`timed out`),o=n.includes(`Authentication failed`)||n.includes(`could not read Username`)||n.includes(`terminal prompts disabled`)||n.includes(`401`)||n.includes(`403`)||n.includes(`Permission denied`),s=n.includes(`SSL certificate`)||n.includes(`unable to access`)&&n.includes(`SSL`),c=n.includes(`Could not resolve host`)||n.includes(`Name or service not known`),l=n.includes(`SAML`)||n.includes(`single sign-on`);return o||l?(r.push(``),r.push(`Cause: Authentication required or credentials not configured.`),r.push(``),r.push(`To fix this, ensure git can access this repository:`),r.push(``),r.push(`  Option 1 - SSH key:`),r.push(`    1. Generate an SSH key: ssh-keygen -t ed25519`),r.push(`    2. Add the public key to your Git hosting account`),r.push(`    3. Use the SSH URL instead: git@<host>:<org>/<repo>.git`),r.push(``),r.push(`  Option 2 - Personal Access Token (PAT):`),r.push(`    1. Create a PAT in your Git hosting Settings > Developer settings > Tokens`),r.push(`    2. For GitHub Enterprise with SAML SSO, authorize the token for your org`),r.push(`    3. Configure git credentials:`),r.push(`       git config --global credential.helper store`),r.push(`       git clone ${e}   (enter PAT as password)`),r.push(``),r.push(`  Option 3 - Git Credential Manager:`),r.push(`    1. Install: https://github.com/git-ecosystem/git-credential-manager`),r.push(`    2. Run: git clone ${e}`),r.push(`    3. Follow the browser-based auth prompt`),r.push(``),r.push(`After configuring credentials, retry: aikit flow add ${e}`)):a?(r.push(``),r.push(`Cause: Connection timed out - the server did not respond within 60 seconds.`),r.push(``),r.push(`Possible reasons:`),r.push(`  - The repository requires VPN access. Ensure your VPN is connected`),r.push(`  - The host is behind a firewall or corporate proxy`),r.push(`  - The URL may be incorrect`),r.push(``),r.push(`Diagnostics:`),r.push(`  1. Verify the URL is correct: ${e}`),r.push(`  2. Test connectivity: git ls-remote ${e}`),r.push(`  3. If behind a proxy, configure git:`),r.push(`     git config --global http.proxy http://proxy:port`),r.push(``),r.push(`If this is a corporate/internal host, you may need to:`),r.push(`  - Connect to the corporate VPN`),r.push(`  - Add the host to your SSH config or git config`),r.push(`  - Ask your IT team to allowlist your machine`),r.push(``),r.push(`After resolving, retry: aikit flow add ${e}`)):s?(r.push(``),r.push(`Cause: SSL/TLS certificate verification failed.`),r.push(``),r.push(`This often happens with corporate proxies or self-signed certificates.`),r.push(``),r.push(`To fix:`),r.push(`  1. If your company uses a custom CA, add it:`),r.push(`     git config --global http.sslCAInfo /path/to/ca-bundle.crt`),r.push(`  2. As a last resort (not recommended for production):`),r.push(`     git config --global http.sslVerify false`),r.push(``),r.push(`After resolving, retry: aikit flow add ${e}`)):c?(r.push(``),r.push(`Cause: Cannot resolve hostname.`),r.push(``),r.push(`Check:`),r.push(`  1. Is the URL correct? ${e}`),r.push(`  2. Are you connected to the internet/VPN?`),r.push(`  3. Can you resolve the host? ping ${i}`),r.push(``),r.push(`After resolving, retry: aikit flow add ${e}`)):(r.push(``),r.push(`Error: ${t}`),n&&r.push(`Details: ${n}`),r.push(``),r.push(`Troubleshooting:`),r.push(`  1. Verify the URL is a valid git repository: git ls-remote ${e}`),r.push(`  2. Check your git credentials and network connectivity`),r.push(`  3. If the repo requires auth, configure credentials first (PAT or SSH key)`),r.push(``),r.push(`After resolving, retry: aikit flow add ${e}`)),r.join(`
+`)}function L(){try{return g(`git`,[`credential-manager`,`--version`],{stdio:`pipe`,timeout:5e3}).status===0}catch{return!1}}function R(e,t){let n=`${e}\n${t}`.toLowerCase();return n.includes(`authentication failed`)||n.includes(`could not read username`)||n.includes(`saml sso`)||n.includes(`terminal prompts disabled`)||n.includes(`host key verification failed`)||n.includes(`permission denied`)||n.includes(`403`)||n.includes(`401`)}var z=class{constructor(e){this.flowsDir=e}clone(e,t){let r=this.repoNameFromUrl(e),i=p(this.flowsDir,r);if(n(i))if(!n(p(i,`.git`)))o(i,{recursive:!0,force:!0});else return{success:!1,error:`Flow "${r}" already installed at ${i}. Use update instead.`};try{if(this.ensureFlowsDir(),t){let n=process.platform===`win32`?`bat`:`sh`,r=p(v(),`git-askpass-${Date.now()}.${n}`);process.platform===`win32`?u(r,`@echo ${t}`,{mode:448}):u(r,`#!/bin/sh\necho "${t}"`,{mode:448});try{let t=g(`git`,[`clone`,`--depth`,`1`,e,i],{stdio:`pipe`,timeout:6e4,env:{...process.env,GIT_TERMINAL_PROMPT:`0`,GIT_ASKPASS:r}});if(t.status!==0){let e=t.stderr?.toString().trim()??``;throw Error(e||t.error?.message||`git clone failed`)}}finally{try{l(r)}catch{}}}else{let t=g(`git`,[`clone`,`--depth`,`1`,e,i],{stdio:`pipe`,timeout:6e4,env:{...process.env,GIT_TERMINAL_PROMPT:`0`,GIT_ASKPASS:``}});if(t.status!==0){let e=t.stderr?.toString().trim()??``;throw Error(e||t.error?.message||`git clone failed`)}}return{success:!0,data:i}}catch(r){n(i)&&o(i,{recursive:!0,force:!0});let a=P(r),s=r instanceof Error?r.message:String(r);if(!t&&R(s,a)&&L()){let t=F(e)||e;console.log(`\nAuthentication required for ${t}.\nGit Credential Manager detected - opening browser for login...\n(If a browser window does not open, check your terminal for a device code.)\n`);try{if(this.ensureFlowsDir(),g(`git`,[`clone`,`--depth`,`1`,e,i],{stdio:`inherit`,timeout:12e4,env:{...process.env,GIT_TERMINAL_PROMPT:`1`}}).status===0)return{success:!0,data:i};n(i)&&o(i,{recursive:!0,force:!0})}catch{n(i)&&o(i,{recursive:!0,force:!0})}}return{success:!1,error:I(e,s,a)}}}update(e){if(!n(e))return{success:!1,error:`Install path not found: ${e}`};try{return h(`git pull --ff-only`,{cwd:e,stdio:`pipe`,timeout:6e4,env:{...process.env,GIT_TERMINAL_PROMPT:`0`,GIT_ASKPASS:``}}),{success:!0}}catch(t){let n=e;try{n=h(`git remote get-url origin`,{cwd:e,stdio:`pipe`,timeout:1e4}).toString().trim()}catch{}let r=P(t),i=t instanceof Error?t.message:String(t);if(R(i,r)&&L()){let t=F(n)||n;console.log(`\nAuthentication required for ${t}.\nGit Credential Manager detected - opening browser for login...\n`);try{if(g(`git`,[`pull`,`--ff-only`],{cwd:e,stdio:`inherit`,timeout:12e4,env:{...process.env,GIT_TERMINAL_PROMPT:`1`}}).status===0)return{success:!0}}catch{}}return{success:!1,error:I(n,i,r)}}}copyLocal(e,r){let i=p(this.flowsDir,r);if(n(i))return{success:!1,error:`Flow "${r}" already installed at ${i}`};try{return this.ensureFlowsDir(),t(e,i,{recursive:!0}),{success:!0,data:i}}catch(e){return{success:!1,error:`Copy failed: ${e instanceof Error?e.message:String(e)}`}}}remove(e){if(!n(e))return{success:!0};try{return o(e,{recursive:!0,force:!0}),{success:!0}}catch(e){return{success:!1,error:`Remove failed: ${e instanceof Error?e.message:String(e)}`}}}runInstallDeps(e){for(let t of e)try{if(t.startsWith(`npm:`)){h(`npx skills add ${t.slice(4)} -g`,{stdio:`pipe`,timeout:12e4});continue}if(t.endsWith(`.git`)||t.includes(`github.com`)){h(`npx skills add ${t} -g`,{stdio:`pipe`,timeout:12e4});continue}return{success:!1,error:`Unknown install entry format: ${t}`}}catch(e){return{success:!1,error:`Install dependency failed for "${t}": ${e instanceof Error?e.message:String(e)}`}}return{success:!0}}getLocalCommit(e){try{return h(`git rev-parse HEAD`,{cwd:e,stdio:`pipe`,timeout:1e4,env:{...process.env,GIT_TERMINAL_PROMPT:`0`}}).toString().trim()||null}catch{return null}}getRemoteCommit(e){try{return h(`git ls-remote origin HEAD`,{cwd:e,stdio:`pipe`,timeout:3e4,env:{...process.env,GIT_TERMINAL_PROMPT:`0`}}).toString().trim().split(/\s+/)[0]||null}catch{return null}}hasUpdates(e){let t=this.getLocalCommit(e);if(!t)return{success:!1,error:`Could not determine local commit (not a git repo?)`};let n=this.getRemoteCommit(e);return n?{success:!0,data:{localCommit:t,remoteCommit:n,hasUpdates:t!==n}}:{success:!1,error:`Could not reach remote to check for updates`}}repoNameFromUrl(e){return d(e).replace(/\.git$/,``)}ensureFlowsDir(){n(this.flowsDir)||r(this.flowsDir,{recursive:!0})}};const B=[new T,new C,new w,new E];function V(e){let t=B.find(t=>t.format===e);if(!t)throw Error(`No adapter for format: ${e}`);return t}function H(e){for(let t of B)if(t.detect(e))return t;return null}var U=class{async load(e,t){if(!n(e))return{success:!1,error:`Source directory not found: ${e}`};let r=H(e);if(!r)return{success:!1,error:`No format adapter matches source: ${e}`};try{let n=await r.parse(e,t),i=this.validate(n);return i.success?{success:!0,data:{manifest:n,format:r.format}}:i}catch(e){return{success:!1,error:`Failed to parse flow: ${e instanceof Error?e.message:String(e)}`}}}async loadWithFormat(e,t,n){let r=V(t);try{let t=await r.parse(e,n),i=this.validate(t);return i.success?{success:!0,data:t}:i}catch(e){return{success:!1,error:`Failed to parse flow: ${e instanceof Error?e.message:String(e)}`}}}validate(e){let t=[];e.name?.trim()||t.push(`Missing flow name`),e.version?.trim()||t.push(`Missing flow version`),e.steps?.length||t.push(`Flow must have at least one step`);let n=new Set(e.steps.map(e=>e.id));for(let r of e.steps??[]){r.id?.trim()||t.push(`Step missing id`),r.instruction?.trim()||t.push(`Step "${r.id}" missing instruction path`);for(let e of r.requires??[])n.has(e)||t.push(`Step "${r.id}" requires unknown step "${e}"`)}return n.size!==(e.steps?.length??0)&&t.push(`Duplicate step IDs found`),t.length>0?{success:!1,error:`Validation failed:\n${t.join(`
+`)}`}:{success:!0}}};function W(){return k().map(e=>({name:e.manifest.name,version:e.manifest.version,source:`builtin`,sourceType:`builtin`,installPath:e.scaffoldDir,format:`native`,registeredAt:`1970-01-01T00:00:00.000Z`,updatedAt:`1970-01-01T00:00:00.000Z`,manifest:e.manifest}))}var G=class{constructor(e){this.registryPath=e}load(){if(!n(this.registryPath))return{version:1,flows:{}};try{let e=i(this.registryPath,`utf-8`);return JSON.parse(e)}catch{return{version:1,flows:{}}}}save(e){let t=f(this.registryPath);n(t)||r(t,{recursive:!0}),u(this.registryPath,JSON.stringify(e,null,2),`utf-8`)}register(e){let t=this.load();return t.flows[e.name]=e,this.save(t),{success:!0}}unregister(e){let t=this.load();return t.flows[e]?(delete t.flows[e],this.save(t),{success:!0}):{success:!1,error:`Flow "${e}" not found in registry`}}get(e){return this.load().flows[e]||(W().find(t=>t.name===e)??null)}list(){let e=this.load(),t=new Set(Object.keys(e.flows)),n=Object.values(e.flows);for(let e of W())t.has(e.name)||n.push(e);return n}has(e){return e in this.load().flows?!0:W().some(t=>t.name===e)}},K=class{constructor(e){this.statePath=e}load(){if(!n(this.statePath))return null;try{let e=i(this.statePath,`utf-8`);return JSON.parse(e)}catch{return null}}save(e){let t=f(this.statePath);n(t)||r(t,{recursive:!0}),u(this.statePath,JSON.stringify(e,null,2),`utf-8`)}start(e,t){let n=this.load();if(n&&n.status===`active`)return{success:!1,error:`Flow "${n.flow}" is already active. Reset it first.`};if(!t.steps.length)return{success:!1,error:`Flow has no steps`};let r=new Date().toISOString(),i={flow:e,status:`active`,currentStep:t.steps[0].id,completedSteps:[],skippedSteps:[],artifacts:{},startedAt:r,updatedAt:r};return this.save(i),{success:!0,data:i}}step(e,t){let n=this.load();if(!n)return{success:!1,error:`No active flow`};if(n.status!==`active`)return{success:!1,error:`Flow is ${n.status}, not active`};if(!n.currentStep)return{success:!1,error:`No current step`};let r=t.steps.findIndex(e=>e.id===n.currentStep);if(r===-1)return{success:!1,error:`Current step "${n.currentStep}" not found in manifest`};let i=new Date().toISOString();switch(e){case`next`:{n.completedSteps.includes(n.currentStep)||n.completedSteps.push(n.currentStep);let e=r+1;e>=t.steps.length?(n.currentStep=null,n.status=`completed`):n.currentStep=t.steps[e].id;break}case`skip`:{n.skippedSteps.includes(n.currentStep)||n.skippedSteps.push(n.currentStep);let e=r+1;e>=t.steps.length?(n.currentStep=null,n.status=`completed`):n.currentStep=t.steps[e].id;break}case`redo`:n.completedSteps=n.completedSteps.filter(e=>e!==n.currentStep),n.skippedSteps=n.skippedSteps.filter(e=>e!==n.currentStep);break}return n.updatedAt=i,this.save(n),{success:!0,data:n}}getStatus(){let e=this.load();return e?{success:!0,data:e}:{success:!1,error:`No active flow`}}reset(){return n(this.statePath)&&l(this.statePath),{success:!0}}recordArtifact(e,t){let n=this.load();return n?(n.artifacts[e]=t,n.updatedAt=new Date().toISOString(),this.save(n),{success:!0}):{success:!1,error:`No active flow`}}},q=class{createSymlinks(t,i,a,o){let s=this.getTargets(t,i);for(let t of s){n(t.baseDir)||r(t.baseDir,{recursive:!0});for(let r of o.agents){let i=p(a,r);if(!n(i))continue;let o=this.getAgentStem(r),s=p(t.baseDir,`${o}${t.extension}`);n(s)&&l(s);let u=m(f(s),i);try{c(u,s,`file`)}catch{try{e(i,s)}catch(e){console.warn(`Failed to create symlink or copy fallback for ${i}: ${e instanceof Error?e.message:String(e)}`)}}}}}removeSymlinks(e,t){let r=this.getTargets(e,t);for(let e of r)if(n(e.baseDir))try{let t=a(e.baseDir,{withFileTypes:!0});for(let n of t)!n.isFile()&&!n.isSymbolicLink()||l(p(e.baseDir,n.name));a(e.baseDir).length===0&&s(e.baseDir)}catch{}}getTargets(e,t){return[{ide:`copilot`,baseDir:p(e,`.github`,`agents`,`flows`,t),extension:`.agent.md`},{ide:`claude-code`,baseDir:p(e,`.claude`,`agents`,`flows`,t),extension:`.md`}]}getAgentStem(e){return d(e).replace(/\.agent\.md$/,``).replace(/\.md$/,``)}};export{C as ClaudePluginAdapter,w as CopilotAdapter,U as FlowLoader,G as FlowRegistryManager,K as FlowStateMachine,N as FoundationIntegration,z as GitInstaller,T as NativeAdapter,E as OpenSpecAdapter,q as SymlinkManager,k as getBuiltinFlows};

package/packages/indexer/dist/index.d.ts

@@ -1,7 +1,197 @@
-import { generateRecordId, hashContent } from "./file-hasher.js";
-import { CrawlOptions, CrawlResult, FilesystemCrawler } from "./filesystem-crawler.js";
-import { ExtractGraphOptions, ExtractedGraph, extractGraph } from "./graph-extractor.js";
-import { FileHashCache } from "./hash-cache.js";
-import { IncrementalIndexer, IndexProgress, IndexResult, ProgressCallback } from "./incremental-indexer.js";
-import { SmartIndexScheduler } from "./smart-index-scheduler.js";
+import { IndexStats, KBConfig } from "../../core/dist/index.js";
+import { GraphEdge, GraphNode, IGraphStore, IKnowledgeStore } from "../../store/dist/index.js";
+import { IEmbedder } from "../../embeddings/dist/index.js";
+
+//#region packages/indexer/src/file-hasher.d.ts
+/**
+ * Generate a deterministic hash for a file's content.
+ * Used for incremental indexing -- skip files that haven't changed.
+ */
+declare function hashContent(content: string): string;
+/**
+ * Generate a deterministic ID for a knowledge record.
+ * Based on source path + chunk index to ensure idempotent upserts.
+ */
+declare function generateRecordId(sourcePath: string, chunkIndex: number): string;
+//#endregion
+//#region packages/indexer/src/filesystem-crawler.d.ts
+interface CrawlResult {
+  /** File path relative to workspace root */
+  relativePath: string;
+  /** Absolute file path */
+  absolutePath: string;
+  /** File content */
+  content: string;
+  /** File extension (lowercase, with dot) */
+  extension: string;
+}
+interface CrawlOptions {
+  /** Glob patterns to exclude */
+  excludePatterns: string[];
+  /** Root directory to crawl */
+  rootDir: string;
+}
+/**
+ * Crawl a directory tree and yield files that should be indexed.
+ */
+declare class FilesystemCrawler {
+  /** Binary file extensions that should always be skipped */
+  private static readonly BINARY_EXTENSIONS;
+  crawl(options: CrawlOptions): Promise<CrawlResult[]>;
+  private walkDir;
+  private isExcluded;
+}
+//#endregion
+//#region packages/indexer/src/graph-extractor.d.ts
+interface ExtractGraphOptions {
+  /** Maps workspace package names to entry module paths without extensions. */
+  workspacePackages?: Map<string, string>;
+}
+interface ExtractedGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+/**
+ * Extract graph nodes and edges from a single file's content.
+ * Produces:
+ * - One "module" node per file
+ * - Symbol nodes (function, class, interface, type, const, enum)
+ * - "defines" edges from module → symbol
+ * - "imports" edges from module → imported module
+ */
+declare function extractGraph(content: string, sourcePath: string, options?: ExtractGraphOptions): ExtractedGraph;
+//#endregion
+//#region packages/indexer/src/hash-cache.d.ts
+/**
+ * Persistent file hash cache.
+ * Stores path->hash mappings in a JSON file to avoid LanceDB round-trips
+ * when checking which files have changed during incremental indexing.
+ */
+declare class FileHashCache {
+  private cache;
+  private readonly filePath;
+  private dirty;
+  constructor(storeDir: string);
+  /** Load cache from disk. Non-fatal if missing or corrupt. */
+  load(): void;
+  get(path: string): string | undefined;
+  set(path: string, hash: string): void;
+  delete(path: string): void;
+  /** Persist cache to disk if changed. */
+  flush(): void;
+  /** Clear all entries and delete file. */
+  clear(): void;
+  get size(): number;
+}
+//#endregion
+//#region packages/indexer/src/incremental-indexer.d.ts
+interface IndexProgress {
+  phase: 'crawling' | 'chunking' | 'embedding' | 'storing' | 'cleanup' | 'done';
+  filesTotal: number;
+  filesProcessed: number;
+  chunksTotal: number;
+  chunksProcessed: number;
+  /** The file currently being processed */
+  currentFile?: string;
+}
+type ProgressCallback = (progress: IndexProgress) => void;
+interface IndexResult {
+  filesProcessed: number;
+  filesSkipped: number;
+  chunksCreated: number;
+  filesRemoved: number;
+  durationMs: number;
+}
+declare class IncrementalIndexer {
+  private readonly embedder;
+  private readonly store;
+  private readonly crawler;
+  private indexing;
+  private graphStore?;
+  private hashCache?;
+  /** Whether an index operation is currently in progress. */
+  get isIndexing(): boolean;
+  constructor(embedder: IEmbedder, store: IKnowledgeStore);
+  /** Set the graph store for auto-population during indexing and cleanup on re-index. */
+  setGraphStore(graphStore: IGraphStore): void;
+  /** Set the hash cache for faster incremental checks. */
+  setHashCache(cache: FileHashCache): void;
+  /**
+   * Index all configured sources. Only re-indexes files that have changed.
+   * Sources are crawled in parallel, and file processing runs concurrently
+   * up to `config.indexing.concurrency` (default: 50% of CPU cores, minimum 2, maximum 4).
+   */
+  index(config: KBConfig, onProgress?: ProgressCallback): Promise<IndexResult>;
+  /**
+   * Crawl sources and return file paths whose content has changed since the last index.
+   * This performs a read-only scan and does not modify the store.
+   */
+  getChangedFiles(config: KBConfig): Promise<string[]>;
+  /**
+   * Index only the specified file paths.
+   * Files that have not changed are skipped.
+   */
+  indexFiles(config: KBConfig, paths: string[], onProgress?: ProgressCallback): Promise<IndexResult>;
+  private doIndex;
+  private doIndexFiles;
+  private crawlSources;
+  private planIndexWork;
+  private getPathsToRemove;
+  private buildWorkspacePackageMap;
+  private processFiles;
+  private cleanupRemovedFiles;
+  /**
+   * Force re-index all files (ignoring hashes).
+   */
+  reindexAll(config: KBConfig, onProgress?: ProgressCallback): Promise<IndexResult>;
+  private doReindex;
+  /**
+   * Get current index statistics.
+   */
+  getStats(): Promise<IndexStats>;
+}
+//#endregion
+//#region packages/indexer/src/smart-index-scheduler.d.ts
+/**
+ * SmartIndexScheduler trickles indexing work over time instead of running
+ * large idle-triggered indexing passes.
+ */
+declare class SmartIndexScheduler {
+  private readonly indexer;
+  private readonly config;
+  private readonly store?;
+  private trickleTimer;
+  private readonly trickleIntervalMs;
+  private readonly batchSize;
+  private readonly priorityQueue;
+  private changedFiles;
+  private lastRefreshTime;
+  private refreshing;
+  constructor(indexer: IncrementalIndexer, config: KBConfig, store?: {
+    createFtsIndex: () => Promise<void>;
+  } | undefined);
+  /** Start the trickle indexing loop. */
+  start(): void;
+  /** Stop the scheduler and clear all timers. */
+  stop(): void;
+  /**
+   * Add file paths to the front of the priority queue for near-term indexing.
+   */
+  prioritize(...paths: string[]): void;
+  getState(): {
+    mode: 'smart';
+    queueSize: number;
+    changedFilesSize: number;
+    intervalMs: number;
+    batchSize: number;
+    running: boolean;
+  };
+  private readPositiveIntEnv;
+  private scheduleTick;
+  private tick;
+  private getCpuCount;
+  private pickFiles;
+  private maybeRefreshChangedFiles;
+}
+//#endregion
 export { type CrawlOptions, type CrawlResult, type ExtractGraphOptions, type ExtractedGraph, FileHashCache, FilesystemCrawler, IncrementalIndexer, type IndexProgress, type IndexResult, type ProgressCallback, SmartIndexScheduler, extractGraph, generateRecordId, hashContent };