snipara-companion 2.3.0 → 3.0.0

package/README.md

@@ -7,10 +7,11 @@
 
 **Ask your repo what breaks if you touch this.**
 
-No global install. No `init`. No account. Your code stays on your machine.
+No global install. No account. Your code stays on your machine.
 
 ```bash
 npx -y snipara-companion impact src/auth/session.ts --source local
+npx -y snipara-companion source init .
 ```
 
 Example output excerpt:
@@ -40,6 +41,7 @@ These commands are useful without hosted Snipara:
 
 | Command                                                      | What it gives you locally                                    |
 | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `source init` / `source sync` / `source status`              | Local source snapshot, document preview, and code overlay    |
 | `impact` / `code impact`                                     | File-level blast-radius from the local code overlay          |
 | `code callers` / `imports` / `neighbors` / `shortest-path`   | Structural repo questions from local files                   |
 | `workflow start` / `phase-start` / `phase-commit` / `resume` | Agent continuity that survives compaction                    |
@@ -73,6 +75,7 @@ Snipara is the upgrade path for team and cross-project intelligence.
 | Need                                            | Local companion           | Hosted Snipara                      |
 | ----------------------------------------------- | ------------------------- | ----------------------------------- |
 | Inspect this repo before editing                | Yes, no account           | Optional hosted code graph          |
+| Activate docs and code without GitHub           | Yes, `source init`        | Provider sync after approval        |
 | Keep code private on this machine               | Yes                       | Use only when explicitly configured |
 | Preserve agent workflow state                   | Yes, `.snipara/` files    | Syncs across machines and agents    |
 | Store/retrieve long tool output                 | Yes, `context-pack`       | Metadata and receipts can be shared |
@@ -85,6 +88,17 @@ graph, cross-machine presence, outcome learning, team coordination, or dashboard
 proof. Keep local mode when the question is simply: "what does this repo say
 will break if I touch this file?"
 
+For folders without Git metadata or users who have not approved GitHub yet, run:
+
+```bash
+npx -y snipara-companion source init .
+npx -y snipara-companion source status --json
+```
+
+This writes `.snipara/source/latest.json`, builds a local document sync preview,
+and refreshes `.snipara/code-overlay/latest.json`. The hosted code graph remains
+the canonical shared graph after provider sync.
+
 ## Install
 
 Use `npx` for one-off checks:

package/dist/index.d.ts

@@ -2750,6 +2750,105 @@ declare function buildAgenticTimeline(options?: {
     cwd?: string;
 }): AgenticTimeline;
 
+type LocalSourceProvider = "local_folder";
+type LocalSourceFileKind = "DOC" | "BINARY" | "CODE" | "CONFIG" | "OTHER";
+type LocalSourceSkippedReason = "ignored" | "too_large" | "read_error";
+type LocalSourceReindexKind = "doc" | "code";
+type LocalSourceReindexMode = "incremental" | "full";
+interface LocalSourceFile {
+    path: string;
+    kind: LocalSourceFileKind;
+    format: string | null;
+    sizeBytes: number;
+    modifiedAt: string;
+    sha256: string;
+}
+interface LocalSourceSkippedFile {
+    path: string;
+    reason: LocalSourceSkippedReason;
+    sizeBytes?: number;
+}
+interface LocalSourceSummary {
+    totalFiles: number;
+    totalBytes: number;
+    byKind: Record<LocalSourceFileKind, number>;
+    skipped: number;
+}
+interface LocalSourceSnapshot {
+    version: "snipara.local_source_snapshot.v1";
+    generatedAt: string;
+    root: string;
+    provider: LocalSourceProvider;
+    revision: string;
+    recursive: boolean;
+    maxFiles: number;
+    maxFileBytes: number;
+    summary: LocalSourceSummary;
+    files: LocalSourceFile[];
+    skipped: {
+        total: number;
+        byReason: Record<LocalSourceSkippedReason, number>;
+        samples: LocalSourceSkippedFile[];
+    };
+    warnings: string[];
+}
+interface LocalSourceSnapshotOptions {
+    dir?: string;
+    recursive?: boolean;
+    maxFiles?: number;
+    maxFileBytes?: number;
+}
+interface LocalSourceComparison {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    unchanged: number;
+}
+interface LocalSourceStatusResult {
+    root: string;
+    snapshotPath: string;
+    previous: LocalSourceSnapshot | null;
+    current: LocalSourceSnapshot;
+    comparison: LocalSourceComparison;
+}
+interface LocalSourceSyncOptions extends LocalSourceSnapshotOptions {
+    prefix?: string;
+    mode?: OnboardFolderMode;
+    deleteMissing?: boolean;
+    apply?: boolean;
+    reindex?: boolean;
+    reindexKind?: LocalSourceReindexKind;
+    reindexMode?: LocalSourceReindexMode;
+    includeGraph?: boolean;
+    json?: boolean;
+}
+interface LocalSourceSyncResult {
+    root: string;
+    snapshotPath: string;
+    snapshot: LocalSourceSnapshot;
+    comparison: LocalSourceComparison;
+    documents: {
+        onboarding: Pick<OnboardFolderManifest, "source" | "classification" | "summary" | "warnings">;
+        dryRun: OnboardFolderManifest["dryRun"];
+    };
+    codeOverlay: {
+        cachePath: string;
+        summary: LocalCodeOverlaySummary;
+    };
+    apply: null | {
+        sync: Record<string, unknown>;
+        reindex?: Record<string, unknown>;
+    };
+    warnings: string[];
+}
+declare function getLocalSourceSnapshotPath(cwd?: string): string;
+declare function buildLocalSourceSnapshot(options?: LocalSourceSnapshotOptions): LocalSourceSnapshot;
+declare function writeLocalSourceSnapshot(snapshot: LocalSourceSnapshot): string;
+declare function readLocalSourceSnapshot(cwd?: string): LocalSourceSnapshot | null;
+declare function compareLocalSourceSnapshots(previous: LocalSourceSnapshot | null, current: LocalSourceSnapshot): LocalSourceComparison;
+declare function buildLocalSourceStatus(options?: LocalSourceSnapshotOptions): LocalSourceStatusResult;
+declare function buildLocalSourceSyncResult(options?: LocalSourceSyncOptions): Promise<LocalSourceSyncResult>;
+
 declare const MANIFEST_VERSION = "snipara.references.v1";
 type ReferenceStatus = "allowed" | "pending" | "denied" | "unsupported";
 interface ReferenceOccurrence {
@@ -3365,6 +3464,7 @@ interface AdaptiveWorkProfile {
     contextBudget: string;
     reasoningDepth: string;
     evidenceRequirements?: string[];
+    preferredProfileStrengths?: string[];
     notes?: string[];
 }
 interface AdaptiveModelRequirements {
@@ -3377,6 +3477,7 @@ interface AdaptiveModelRequirements {
     capabilities: string[];
     forbiddenCapabilities: string[];
     writeScope: string[];
+    structuredOutputRequired?: boolean;
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
     catalogLimit?: number;
@@ -3394,13 +3495,13 @@ interface AdaptiveRoutingCard {
     requirements: AdaptiveModelRequirements;
     recommendedWorkerClass: string;
     costEstimate: AdaptiveRoutingCostEstimate;
-    humanApprovalRequired: true;
+    humanApprovalRequired: boolean;
     fallback: "main_agent";
     reasons: string[];
     warnings: string[];
 }
 interface AdaptiveRoutingGatewayStatus {
-    source: "hosted_mcp";
+    source: "hosted_mcp" | "local_orchestrator";
     success: boolean;
     resolutionStatus?: string;
     candidateCount: number;
@@ -3409,14 +3510,32 @@ interface AdaptiveRoutingGatewayStatus {
 }
 interface AdaptiveRoutingRuntimeCatalog {
     version?: string;
+    source?: string;
+    provider?: string;
+    baseUrl?: string;
+    models?: string[];
+    apiPaths?: Record<string, unknown>;
+    workerEndpoints?: Record<string, Record<string, unknown>>;
+    workerProfiles?: Record<string, Record<string, unknown>>;
     candidates: Array<Record<string, unknown>>;
 }
+interface AdaptiveRoutingResolution {
+    status?: string;
+    selected?: Record<string, unknown>;
+    policyDecision?: Record<string, unknown>;
+    evaluatedCount?: number;
+    rejectedCount?: number;
+    fallback?: string;
+    reasons?: string[];
+    warnings?: string[];
+}
 interface AdaptiveWorkRoutingRecommendation {
     workProfile: AdaptiveWorkProfile;
     requirements: AdaptiveModelRequirements;
     routingCard: AdaptiveRoutingCard;
     gateway?: AdaptiveRoutingGatewayStatus;
     runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
+    resolution?: AdaptiveRoutingResolution;
 }
 interface AdaptiveWorkRoutingOptions {
     query: string;
@@ -3426,6 +3545,8 @@ interface AdaptiveWorkRoutingOptions {
     allowedEndpointTypes?: string[];
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
+    preferredProfileStrengths?: string[];
+    structuredOutputRequired?: boolean;
     catalogLimit?: number;
     dailyBudgetCents?: number;
     monthlyBudgetCents?: number;
@@ -3458,6 +3579,7 @@ interface OrchestratorHandoffArtifact {
         routingCard?: AdaptiveRoutingCard;
         gateway?: AdaptiveRoutingGatewayStatus;
         runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
+        resolution?: AdaptiveRoutingResolution;
     };
     task: {
         title: string;
@@ -3521,4 +3643,4 @@ declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions):
 declare function buildAdaptiveWorkRoutingRecommendation(options: AdaptiveWorkRoutingOptions): AdaptiveWorkRoutingRecommendation;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, agentReadinessAuditCommand, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, agentReadinessAuditCommand, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff };