snipara-companion 1.4.2 → 1.4.4

package/README.md

@@ -4,8 +4,9 @@
 
 `snipara-companion` adds Git-style continuity commands for agent work: status,
 briefs, timelines, phase commits, handoffs, resume, diagnostics, hooks, folder
-onboarding, and command-line access around Snipara Hosted MCP. It complements
-the hosted context and memory surface; it is not the primary runtime for agents.
+onboarding, local Mini Snipara bridges, and command-line access around Snipara
+Hosted MCP. It complements the hosted context and memory surface; it is not the
+primary runtime for agents.
 
 In this repository, the source currently lives in `packages/cli`, and the installed executable is `snipara-companion`.
 
@@ -15,10 +16,42 @@ This package complements `snipara-mcp`. It does not replace it.
 flowchart LR
     Project["Local project"] --> Companion["snipara-companion"]
     Companion --> Diagnostics["status, brief, timeline, phase commits, handoff"]
+    Companion --> Memory["snipara-memory (optional local memory)"]
+    Companion --> Evals["snipara-evals (optional local evals)"]
     Companion --> Hosted["Snipara Hosted MCP / API"]
     Hosted --> Agents["Codex, Claude Code, Cursor, ChatGPT"]
 ```
 
+## Mini Snipara Open Stack
+
+`snipara-companion` is the local workflow layer in the open Mini Snipara stack:
+
+| Repo                                                                | Role                                                                                                            | Account required                         |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| [`snipara-companion`](https://github.com/Snipara/snipara-companion) | Local workflow continuity, hooks, handoffs, and hosted bridges                                                  | No for local state; yes for hosted calls |
+| [`snipara-memory`](https://github.com/Snipara/snipara-memory)       | Local durable project memory engine and MCP/API wrapper                                                         | No                                       |
+| [`snipara-evals`](https://github.com/Snipara/snipara-evals)         | Deterministic Project Intelligence evals for handoffs, context, decisions, impact, verification, and continuity | No                                       |
+
+Hosted Snipara remains the managed layer for source authority, reviewed memory,
+team-wide presence, shared claims/locks, conflict alarms, GitHub checks,
+dashboard live views, and Cloud code graph impact. Local commands are useful for
+single-machine continuity and CI artifacts, but they cannot prove what another
+human or agent is doing on a different machine unless the hosted collaboration
+backend is configured.
+
+## Local vs Hosted Capabilities
+
+| Capability                                   | Local/open stack                   | Hosted Snipara                              |
+| -------------------------------------------- | ---------------------------------- | ------------------------------------------- |
+| Workflow state, timeline, handoff files      | Yes                                | Syncs and enriches when configured          |
+| Local project memory                         | Via `snipara-memory`               | Managed, reviewed, scoped memory            |
+| Project Intelligence eval artifacts          | Via `snipara-evals`                | Can use hosted context/code graph as inputs |
+| Git hooks and local guards                   | Yes                                | Stronger with hosted guard decisions        |
+| Presence across machines and agents          | No                                 | Yes                                         |
+| Shared claims/locks and stale lease handling | Local only is advisory             | Yes                                         |
+| GitHub checks and dashboard live views       | No                                 | Yes                                         |
+| Code graph impact and symbol cards           | Local overlay only where available | Cloud code graph                            |
+
 ## When To Use It
 
 | If you need...                                            | Install...               |
@@ -59,6 +92,18 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
+## New In 1.4.4
+
+- Adds `snipara-companion memory local -- <args...>` as a thin bridge to the
+  open `snipara-memory` engine for no-account local memory workflows.
+- Adds `snipara-companion eval export` to write a `snipara-evals` case from
+  local workflow, Team Sync, file, command, and expected-signal inputs.
+- Adds `snipara-companion eval run` to execute `snipara-evals` through `npx` or a
+  configured local runner.
+- Clarifies the open Mini Snipara stack boundary: local continuity and evals are
+  open, while team-wide presence, shared locks, GitHub checks, dashboards, and
+  Cloud code graph remain hosted Snipara capabilities.
+
 ## New In 1.4.2
 
 - Adds `snipara-companion collaboration start|watch|claim|guard|release|status`
@@ -514,6 +559,16 @@ snipara-companion memory audit --scope project --include-inactive
 snipara-companion memory health --scope project --json
 snipara-companion memory clean-candidates --scope project --limit-per-bucket 10
 snipara-companion memory compact --scope project --json
+snipara-companion memory local -- version
+snipara-companion eval export \
+  --summary "Implemented auth hardening and ran tests" \
+  --decision "Code graph remains hosted" \
+  --verification "pnpm test" \
+  --continuity "Leave a concise next-step handoff" \
+  --files src/auth.ts tests/auth.test.ts \
+  --command-run "pnpm test" \
+  --output .snipara/evals/auth-hardening.json
+snipara-companion eval run .snipara/evals/auth-hardening.json --strict
 snipara-companion chunk get --chunk-id chunk_123
 snipara-companion multi-query --queries "auth flow" "rate limiting"
 snipara-companion orchestrate --query "understand the auth architecture"
@@ -686,6 +741,9 @@ Semantics:
 - `snipara-companion memory health` = direct hosted `snipara_memory_health` diagnostics for active counts, stale/noise/anomaly samples, and auto-compaction threshold status
 - `snipara-companion memory clean-candidates` = direct hosted `snipara_memory_clean_candidates` review packet for noise, stale memories, duplicates, category anomalies, and human review queues
 - `snipara-companion memory compact` = hosted compaction preview only; it always calls `snipara_memory_compact` with `dry_run=true` and never mutates memory
+- `snipara-companion memory local -- <args...>` = pass-through to the open `snipara-memory` CLI for local no-account memory workflows
+- `snipara-companion eval export` = write a `snipara-evals` case JSON from local workflow/team-sync state and explicit expected signals
+- `snipara-companion eval run <case.json...>` = run `snipara-evals` locally through `npx` or `SNIPARA_EVALS_RUNNER`
 - `snipara-companion reindex` = trigger or poll hosted `snipara_reindex`; use after uploads when immediate chunk availability matters
 - `snipara-companion code *` = direct access to the code graph tools without routing through `snipara_context_query`
 - `snipara-companion recall` = direct durable memory lookup for decisions, learnings, preferences, and carryover

package/dist/index.d.ts

@@ -1305,6 +1305,68 @@ declare function memoryCompactCommand(options: MemoryCompactCommandOptions): Pro
 declare function buildMemoryAudit(options: MemoryAuditCommandOptions): Promise<MemoryAuditResult>;
 declare function memoryAuditCommand(options: MemoryAuditCommandOptions): Promise<void>;
 
+type ExpectedSectionName = "context" | "decisions" | "impact" | "verification" | "continuity";
+interface LocalMemoryCommandOptions {
+    binary?: string;
+    args?: string[];
+}
+interface EvalExportOptions {
+    id?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+    context?: string[];
+    decision?: string[];
+    impact?: string[];
+    verification?: string[];
+    continuity?: string[];
+    files?: string[];
+    commandRun?: string[];
+    output?: string;
+    dir?: string;
+    json?: boolean;
+}
+interface EvalRunOptions {
+    cases: string[];
+    runner?: string;
+    packageSpec?: string;
+    json?: boolean;
+    strict?: boolean;
+}
+interface EvalCaseArtifact {
+    id: string;
+    name?: string;
+    description?: string;
+    tags: string[];
+    expected: Partial<Record<ExpectedSectionName, Array<{
+        id: string;
+        text?: string;
+        statement?: string;
+        target?: string;
+        check?: string;
+        command?: string;
+        handoff?: string;
+        keywords: string[];
+        files?: string[];
+    }>>>;
+    observed: {
+        answer: string;
+        filesChanged: string[];
+        commandsRun: string[];
+        artifacts: Array<{
+            path: string;
+            content: string;
+        }>;
+    };
+    thresholds: {
+        overall: number;
+    };
+}
+declare function buildEvalCaseArtifact(options?: EvalExportOptions): EvalCaseArtifact;
+declare function memoryLocalCommand(options: LocalMemoryCommandOptions): Promise<void>;
+declare function evalExportCommand(options: EvalExportOptions): Promise<void>;
+declare function evalRunCommand(options: EvalRunOptions): Promise<void>;
+
 interface VerifyCommandOptions {
     task?: string;
     qualifiedName?: string;
@@ -2403,4 +2465,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationHooksInstallPlan, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationHooksInstallPlan, buildEvalCaseArtifact, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };