@structured-vibe-coding/core 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1343,6 +1343,11 @@ declare function agentKickoffMessage(opts: {
     changeId: string;
     /** What just happened, e.g. "new change", "advanced to implement" */
     event?: string;
+    /**
+     * When set, replaces the default "do current stage work" tail
+     * (used by sdd refine and other specialized modes).
+     */
+    instructions?: string;
 }): string;
 /** Write .sdd/active-context.md for the current change. */
 declare function refreshActiveAgentContext(projectRoot: string): Promise<string | null>;
@@ -1398,7 +1403,7 @@ declare function uniqueChangeDirName(base: string, taken: Set<string>): string;
  * Packaged default assets shipped with @structured-vibe-coding/core.
  * Resolves correctly for:
  * - package layout: packages/core/dist/index.js → ../defaults
- * - VS Code bundle: packages/vscode/dist/extension.js → ./defaults (copied at build)
+ * - source/tests: packages/core/src → ../defaults
  */
 declare function defaultsRoot(): string;
 declare function defaultWorkflowsDir(): string;
@@ -1423,4 +1428,273 @@ declare function copyDirSkipExisting(src: string, dest: string): Promise<void>;
 declare function writeTextIfMissing(path: string, content: string): Promise<boolean>;
 declare function removePath(path: string): Promise<void>;
 
-export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_INIT_INTEGRATION, type Gate, GateSchema, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, PROTOCOL_MD, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, agentHostPaths, agentKickoffMessage, approveGate, archiveDir, buildAgentPrompt, buildContext, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, clearActiveIf, completeChange, configPath, copyDir, copyDirSkipExisting, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, fallbackIncompleteStageId, firstActiveStageId, formatStatus, getActiveChangeId, getIntegration, getStage, incompletePriorStageErrors, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, isInitialized, isStageSkipped, isSubstantiveArtifactContent, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadInstalledAgent, loadWorkflow, memoryDir, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removeOtherAgentHosts, removePath, renderThinAgent, resolveChangeId, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, uniqueChangeDirName, workflowsDir, writeAgentHandoff, writeText, writeTextIfMissing, writeYaml };
+/**
+ * Public + internal types for the on-demand structure-aware code context pipeline.
+ * Contracts: LLD §2.1 / research §6.5.
+ */
+interface CodeContextCaps {
+    /** Max source files to fully parse (after focus expansion). Default: 40 */
+    maxFiles: number;
+    /** Max ranked symbols to consider for slicing. Default: 30 */
+    maxSymbols: number;
+    /** Max code slices in output. Default: 20 */
+    maxSlices: number;
+    /** Max lines per slice body. Default: 80 */
+    maxLinesPerSlice: number;
+    /** Soft budget for entire markdown body (approx). Default: 8000 */
+    maxOutputLines: number;
+    /** Approx token budget (chars/4 heuristic OK for v1). Default: 12000 */
+    maxTokensApprox: number;
+    /** Max hop distance on import graph from seed files. Default: 1 */
+    maxImportHops: number;
+}
+declare const DEFAULT_CODE_CONTEXT_CAPS: CodeContextCaps;
+interface CodeContextRequest {
+    projectRoot: string;
+    /** Active change id when known; null = flags-only / no change pack signals */
+    changeId?: string | null;
+    /** Explicit paths (files or dirs), repo-relative or absolute */
+    paths?: string[];
+    /** Symbol names to prioritize (e.g. function/class/export) */
+    symbols?: string[];
+    /** Free-text focus (task phrase); used for keyword ranking only */
+    query?: string;
+    caps?: Partial<CodeContextCaps>;
+    /** When true, include more structural neighbors within caps. Default false */
+    includeNeighbors?: boolean;
+    /**
+     * If set, also write regenerable markdown to this absolute path.
+     * Core may write the file; CLI decides default path under changes/<id>/.
+     */
+    writeArtifactTo?: string | null;
+}
+type CodeContextGapCode = "no_focus" | "path_missing" | "path_denied_secret" | "path_ignored" | "unsupported_language" | "parse_error" | "empty_extract" | "cap_truncated" | "no_active_change" | "change_not_found" | "adapter_unavailable";
+interface CodeContextGap {
+    code: CodeContextGapCode;
+    message: string;
+    path?: string;
+    detail?: string;
+}
+type SymbolKind = "function" | "class" | "interface" | "type" | "const" | "export" | "unknown";
+interface SymbolInfo {
+    name: string;
+    kind: SymbolKind;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    exported: boolean;
+}
+interface CodeSlice {
+    id: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    symbolName?: string;
+    reason: string;
+    body: string;
+}
+interface CodeContextSummary {
+    focusPaths: string[];
+    focusSymbols: string[];
+    keywords: string[];
+    filesAnalyzed: number;
+    symbolsExtracted: number;
+    slicesEmitted: number;
+    truncated: boolean;
+}
+interface CodeContextResult {
+    ok: boolean;
+    markdown: string;
+    summary: CodeContextSummary;
+    slices: CodeSlice[];
+    gaps: CodeContextGap[];
+    artifactPath?: string;
+}
+/** Internal focus plan after FocusResolver. */
+interface FocusPlan {
+    seedPaths: string[];
+    seedSymbols: string[];
+    keywords: string[];
+    candidatePaths: string[];
+    changeId: string | null;
+    notes: string[];
+}
+declare function mergeCaps(partial?: Partial<CodeContextCaps>): CodeContextCaps;
+
+interface LanguageAdapter {
+    readonly id: string;
+    readonly extensions: string[];
+    /**
+     * Extract symbols + imports/exports + local references.
+     * Must not throw for recoverable parse issues — return ok:false + errors.
+     */
+    extract(input: {
+        filePath: string;
+        source: string;
+        projectRoot: string;
+    }): Promise<AdapterExtractResult> | AdapterExtractResult;
+}
+interface AdapterExtractResult {
+    ok: boolean;
+    language: string;
+    symbols: SymbolInfo[];
+    imports: {
+        from: string;
+        names?: string[];
+    }[];
+    exports: {
+        name: string;
+        kind?: string;
+    }[];
+    /** Optional: name references found in this file (for GraphLite) */
+    references?: {
+        name: string;
+        line: number;
+    }[];
+    errors?: string[];
+}
+
+/**
+ * Formatter: stable agent-facing markdown (LLD §2.6).
+ */
+
+declare function formatJsonSummary(summary: CodeContextSummary, gaps: CodeContextGap[], slices: CodeSlice[], ok: boolean): string;
+
+/**
+ * FocusResolver: resolve seed paths, symbols, keywords from request + change pack.
+ * LLD §2.3 / research §5.2–5.3.
+ */
+
+declare function tokenizeKeywords(text: string): string[];
+interface ResolveFocusResult {
+    plan: FocusPlan;
+    gaps: CodeContextGap[];
+}
+/**
+ * Resolve FocusPlan from request. Does not hard-fail; caller treats empty seeds as no_focus.
+ */
+declare function resolveFocus(request: CodeContextRequest, options?: {
+    maxCandidateWalk?: number;
+}): Promise<ResolveFocusResult>;
+
+/**
+ * Hard-deny secret/credential paths before parse (LLD §2.10 / ARB #3, #6).
+ * Never put denied path contents into slices or gap detail.
+ */
+/**
+ * Returns true if the path should never be analyzed (secret/credentials risk).
+ * Matches on normalized path segments and basename.
+ */
+declare function isSecretPath(filePath: string): boolean;
+
+/**
+ * Practical ignore filters for noise paths (soft-skip, gap path_ignored).
+ */
+/**
+ * Soft-skip noise: node_modules, dist, coverage, binaries.
+ * Does not include secret paths (those are hard-deny via secrets.ts).
+ */
+declare function isIgnoredPath(filePath: string): boolean;
+type PathFilterKind = "allowed" | "secret" | "ignored";
+declare function classifyPath(filePath: string): PathFilterKind;
+
+/**
+ * Extension → adapter registry. Default maps TS/JS only.
+ * Unknown extensions: no adapter (orchestrator soft-skips).
+ */
+declare class AdapterRegistry {
+    private byExt;
+    constructor(adapters?: LanguageAdapter[]);
+    getByPath(filePath: string): LanguageAdapter | undefined;
+    hasExtension(ext: string): boolean;
+}
+
+/**
+ * TypeScript/JavaScript LanguageAdapter using the TypeScript Compiler API.
+ *
+ * Packaging (research §4.2 / ARB #5):
+ * - `typescript` is a **runtime dependency** of @structured-vibe-coding/core.
+ * - Dual TypeScript copies in consumer monorepos are intentional isolation:
+ *   this adapter uses core's own `typescript` for syntactic `createSourceFile`
+ *   only. It never loads the host project's TypeScript instance or merges a
+ *   full Program / typechecker.
+ */
+
+declare const typescriptAdapter: LanguageAdapter;
+
+/**
+ * Shallow text fallback for unknown languages.
+ * Exists for tests / future opt-in only — NOT used by default for unknown langs
+ * (research §4.4: skip + unsupported_language gap).
+ */
+declare const fallbackAdapter: LanguageAdapter;
+
+/**
+ * On-demand structure-aware code context pipeline (Option A).
+ * Public entry: generateCodeContext
+ */
+
+/** Optional deps for tests (inject adapters). */
+type GenerateCodeContextDeps = {
+    adapters?: LanguageAdapter[];
+    now?: () => Date;
+};
+/**
+ * Main entry: on-demand pipeline. Partial success returns ok:true with gaps.
+ * Hard failures return ok:false with gaps and minimal markdown explaining failure.
+ */
+declare function generateCodeContext(request: CodeContextRequest, deps?: GenerateCodeContextDeps): Promise<CodeContextResult>;
+
+/**
+ * Stage-scoped refine: plan + brief for the coding agent.
+ * Constitution is read-only; prior pack artifacts are impact-scanned;
+ * process is never blocked.
+ */
+
+type RefineMode = "refine" | "analyze";
+interface BuildRefinePlanOptions {
+    projectRoot: string;
+    config: Config;
+    changeId: string;
+    /** Stage to refine (default: current meta.stage) */
+    stageId?: string;
+    /** Only edit focus-stage files; still read prior + constitution */
+    focusOnly?: boolean;
+    mode?: RefineMode;
+}
+interface RefineArtifactRef {
+    stageId: string;
+    path: string;
+    required: boolean;
+    absPath: string;
+}
+interface RefinePlan {
+    changeId: string;
+    title: string;
+    workflow: string;
+    focusStageId: string;
+    focusStageTitle: string;
+    mode: RefineMode;
+    focusOnly: boolean;
+    focusArtifacts: RefineArtifactRef[];
+    priorArtifacts: RefineArtifactRef[];
+    laterArtifacts: RefineArtifactRef[];
+    constitutionPath: string;
+    constitutionExists: boolean;
+    changePath: string;
+    briefPath: string;
+    reportPath: string;
+    openItemsPath: string;
+    /** Short CLI kickoff line */
+    kickoff: string;
+    /** Full brief markdown written to briefPath */
+    briefMarkdown: string;
+}
+/**
+ * Build a refine plan for the active (or given) change and optional stage.
+ */
+declare function buildRefinePlan(opts: BuildRefinePlanOptions): Promise<RefinePlan>;
+/** Write refine brief under the change pack (and a pointer under .sdd/). */
+declare function writeRefineBrief(plan: RefinePlan, projectRoot: string): Promise<string>;
+
+export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdapterExtractResult, AdapterRegistry, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type BuildRefinePlanOptions, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type CodeContextCaps, type CodeContextGap, type CodeContextGapCode, type CodeContextRequest, type CodeContextResult, type CodeContextSummary, type CodeSlice, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_CODE_CONTEXT_CAPS, DEFAULT_INIT_INTEGRATION, type FocusPlan, type Gate, GateSchema, type GenerateCodeContextDeps, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, type LanguageAdapter, PROTOCOL_MD, type RefineArtifactRef, type RefineMode, type RefinePlan, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, type SymbolInfo, type SymbolKind, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, agentHostPaths, agentKickoffMessage, approveGate, archiveDir, buildAgentPrompt, buildContext, buildRefinePlan, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, classifyPath, clearActiveIf, completeChange, configPath, copyDir, copyDirSkipExisting, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, fallbackAdapter, fallbackIncompleteStageId, firstActiveStageId, formatJsonSummary, formatStatus, generateCodeContext, getActiveChangeId, getIntegration, getStage, incompletePriorStageErrors, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, isIgnoredPath, isInitialized, isSecretPath, isStageSkipped, isSubstantiveArtifactContent, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadInstalledAgent, loadWorkflow, memoryDir, mergeCaps, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removeOtherAgentHosts, removePath, renderThinAgent, resolveChangeId, resolveFocus, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, tokenizeKeywords, typescriptAdapter, uniqueChangeDirName, workflowsDir, writeAgentHandoff, writeRefineBrief, writeText, writeTextIfMissing, writeYaml };