snipara-companion 1.3.8 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snipara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,31 +1,70 @@
 # snipara-companion
 
-**Local helper CLI for Snipara agent workflows.**
+**Workflow continuity for AI coding agents. Start work, commit phases, resume anywhere.**
 
-`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.
+`snipara-companion` is the local workflow layer for agentic coding work. It gives
+AI coding agents Git-style continuity commands: status, briefs, timelines, phase
+commits, handoffs, resume, diagnostics, hooks, folder onboarding, and optional
+Hosted Snipara context calls.
 
-In this repository, the source currently lives in `packages/cli`, and the installed executable is `snipara-companion`.
+Use it as the local runtime for the open Snipara stack:
 
-This package complements `snipara-mcp`. It does not replace it.
+- [`snipara-companion`](https://github.com/Snipara/snipara-companion) keeps agent work resumable.
+- [`snipara-memory`](https://github.com/Snipara/snipara-memory) provides durable local project memory primitives.
+- [`snipara-evals`](https://github.com/Snipara/snipara-evals) measures project-intelligence quality for AI coding agents.
+
+Hosted Snipara adds managed context, reviewed memory, team sync, code graph
+impact, source authority, dashboards, and production operations.
 
 ```mermaid
 flowchart LR
     Project["Local project"] --> Companion["snipara-companion"]
-    Companion --> Diagnostics["status, brief, timeline, phase commits, handoff"]
-    Companion --> Hosted["Snipara Hosted MCP / API"]
-    Hosted --> Agents["Codex, Claude Code, Cursor, ChatGPT"]
+    Companion --> Local["status, timeline, handoff, resume"]
+    Companion --> Memory["optional local/project memory"]
+    Companion --> Hosted["optional Hosted Snipara MCP / API"]
+    Hosted --> Intelligence["project intelligence, code graph, reviewed memory"]
 ```
 
+## Open Source Boundary
+
+`snipara-companion` is local-first. It should be useful on a repository even
+when the user has no Snipara account.
+
+| Mode | What works |
+| --- | --- |
+| Local only | `status`, `git summary`, `timeline`, workflow state, `phase-commit`, `final-commit`, local Team Sync handoffs, `code sync`, local code overlay |
+| Local + `snipara-memory` | local `recall`, `query`, `session-bootstrap`, and local memory in `brief` |
+| Snipara Cloud connected | all local features plus hosted memory, Project Intelligence context, What Changed, MCP context, code graph impact, symbol cards, dashboards, and operations |
+
+Cloud wins when connected: if the workspace has a valid Snipara API key and
+project binding, hosted commands use Cloud surfaces. Local fallbacks only run
+when Cloud is not configured.
+
+Open source in this repo:
+
+- local workflow files under `.snipara/`
+- status, git summary, timeline, handoff, resume, phase-commit, and final-commit commands
+- local hook/install helpers for supported AI coding clients
+- diagnostic and verification-plan facades
+- optional `snipara-memory` local fallback for memory recall/session context
+- optional calls to Hosted Snipara when project auth is configured
+
+Hosted Snipara:
+
+- managed MCP context and chunk retrieval
+- reviewed project memory and authority scoring
+- team sync and dashboard workflows
+- code graph impact chains, symbol cards, and verification plans
+- production reliability, tenancy, analytics, and operations
+
 ## When To Use It
 
 | If you need...                                            | Install...               |
 | --------------------------------------------------------- | ------------------------ |
-| MCP tools, OAuth login, project-scoped context and memory | `snipara-mcp`            |
-| One-command Hosted MCP + companion setup                  | `create-snipara`         |
+| Hosted MCP setup and project-scoped context               | `create-snipara`         |
 | Git-style local continuity, workflow modes, and hooks     | `snipara-companion`      |
+| Local durable project memory primitives                   | `snipara-memory`         |
+| Project-intelligence evals for agent traces               | `snipara-evals`          |
 | Production gates, drift checks, and htask orchestration   | `snipara-orchestrator`   |
 | OpenClaw-specific automation hooks                        | `snipara-openclaw-hooks` |
 
@@ -59,6 +98,20 @@ yarn global add snipara-companion
 snipara-companion
 ```
 
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm type-check
+pnpm test
+pnpm pack:smoke
+```
+
+This standalone repository is mirrored from the Snipara monorepo package source
+while the public repo is being bootstrapped. The npm package is
+`snipara-companion`.
+
 ## New In 1.3.7
 
 - Hardens `memory-guard check` with `--confirmed-by-user "<confirmation>"`
@@ -106,6 +159,7 @@ session with `snipara-companion`:
 
 ```bash
 snipara-companion status
+snipara-companion git summary
 snipara-companion brief --task "ship auth hardening" --changed-files src/auth.ts
 snipara-companion timeline
 snipara-companion workflow phase-commit build --summary "tests green"
@@ -116,6 +170,8 @@ snipara-companion workflow resume --include-session-context
 
 - `status` is the Git-style local work status: workflow phase, latest phase
   commit, git dirtiness, Team Sync handoffs, local risks, and next action.
+- `git summary` is a local-only Git companion view: branch, HEAD, upstream
+  ahead/behind, dirty files, recent commits, and suggested next commands.
 - `brief` is the short alias for `intelligence brief`.
 - `timeline` is the Git-style log for workflow starts, phase starts, phase
   commits, final commits, and Team Sync handoffs.
@@ -140,9 +196,11 @@ The mental model is intentionally close to Git:
 API only for the final Team Sync handoff. The CLI sends a compact summary with a
 longer timeout, retries once with a shorter summary on transient hosted failures,
 and then records a local fallback handoff in `.snipara/team-sync/session.json`
-if the hosted call still times out. A hosted final-commit timeout does not modify
-Git state. Custom final-commit categories are namespaced under `final-commit`
-before the hosted call so they stay on the handoff-only path.
+if the hosted call still times out. Without Cloud config, `final-commit` closes
+the local workflow and writes the local handoff directly. A hosted final-commit
+timeout does not modify Git state. Custom final-commit categories are namespaced
+under `final-commit` before the hosted call so they stay on the handoff-only
+path.
 
 ## Verification Plans
 
@@ -633,6 +691,7 @@ Semantics:
 - `snipara-companion workflow run --mode orchestrate` = explicit hosted orchestrator flow for deeper multi-step exploration; use the Python `snipara-orchestrator` package for production gates and htasks
 - `snipara-companion workflow run` = suggests Snipara Sandbox when the query calls for validation, execution, data transforms, or heavier FULL/orchestrated work
 - `snipara-companion status` = top-level agentic work status across local workflow state, git dirtiness, and Team Sync carryover
+- `snipara-companion git summary` = local-only Git companion summary with branch, HEAD, upstream ahead/behind, dirty files, recent commits, and handoff-oriented next commands
 - `snipara-companion brief` = short alias for `snipara-companion intelligence brief`
 - `snipara-companion timeline` = local timeline of workflow starts, phase starts, phase commits, final commits, and Team Sync handoffs
 - `snipara-companion handoff` = top-level agent-ready Markdown/JSON handoff artifact plus the same local/hosted Team Sync handoff persistence
@@ -641,15 +700,15 @@ Semantics:
 - `snipara-companion workflow scaffold --preset project-intelligence-continuity-layer` = creates a four-phase managed plan for memory authority, code impact, continuity summaries, and release/docs surfaces
 - `snipara-companion workflow phase-start` = marks the current phase and prints the required Snipara context gate plus code-impact / symbol-card gates; runtime-marked phases also get a stable Snipara Sandbox session binding
 - `snipara-companion workflow runtime-checkpoint` = captures a resume-ready Snipara Sandbox checkpoint for one phase using local workflow state plus a hosted automation event when configured
-- `snipara-companion workflow phase-commit` = calls hosted `snipara_end_of_task_commit` for that phase, updates local state, and advances the next phase
-- `snipara-companion workflow resume` = reloads local workflow state plus hosted durable/session memory after compaction or resume, then appends the latest hosted Team Sync handoff/checkpoint context when available; runtime-bound phases also print a Snipara Sandbox reattach or rehydrate plan; rerun `workflow phase-start` before editing again
+- `snipara-companion workflow phase-commit` = updates local workflow state and advances the next phase; when Cloud is connected it also calls hosted `snipara_end_of_task_commit`
+- `snipara-companion workflow resume` = reloads local workflow state plus hosted durable/session memory when Cloud is connected, or local `snipara-memory` session context when available; runtime-bound phases also print a Snipara Sandbox reattach or rehydrate plan; rerun `workflow phase-start` before editing again
 - `snipara-companion workflow resume` does not snapshot or exactly restore a live Snipara Sandbox process; exact process restore remains a roadmap item
 - `snipara-companion team-sync start-work` = keeps the local session file and fetches the hosted Start Work Brief when the workspace has project auth
 - `snipara-companion team-sync handoff` = keeps the local handoff record and publishes the hosted handoff capsule when project auth is available
 - `snipara-companion team-sync what-changed` = prints the local state summary and the hosted What Changed For Me response when configured
 - `snipara-companion team-sync sweep` = archives stale local work items after an inactivity threshold; default is 14 days and `--dry-run` previews the cleanup
 - `snipara-companion team-sync resume` = reloads local carryover plus the hosted latest handoff and checkpoint-aware resume guidance when available
-- `snipara-companion final-commit` / `workflow final-commit` = final hosted commit for the managed workflow
+- `snipara-companion final-commit` / `workflow final-commit` = closes the managed workflow locally; when Cloud is connected it also persists the final hosted handoff, otherwise it writes a local Team Sync handoff
 - `snipara-companion code symbol-card` = direct paid Context `snipara_code_symbol_card` for an important symbol before editing, with an agent guidance summary before raw JSON
 - `snipara-companion code impact` = direct paid Context `snipara_code_impact` for changed files, a file, or a symbol before risky changes, with risk/actions/gaps summarized before raw JSON
 - `snipara-companion doctor` = local readiness check for Snipara auth, deterministic hosted tool catalog access, Snipara Sandbox, Snipara Sandbox MCP wiring, provider keys, and Docker
@@ -666,9 +725,10 @@ Semantics:
 - `snipara-companion memory compact` = hosted compaction preview only; it always calls `snipara_memory_compact` with `dry_run=true` and never mutates memory
 - `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
-- `snipara-companion session-bootstrap` = durable memory first, optional weak session carryover second
-- `snipara-companion task-commit` = durable task/phase/workflow outcomes only, not a mechanical mirror of every Git commit
+- `snipara-companion recall` = Cloud durable memory lookup when connected; otherwise local `snipara-memory` recall when installed
+- `snipara-companion query` = Cloud MCP context query when connected; otherwise local `snipara-memory` recall-style query when installed
+- `snipara-companion session-bootstrap` = Cloud durable/session memory when connected; otherwise local `snipara-memory` session bundle when installed
+- `snipara-companion task-commit` = hosted durable task/phase/workflow outcomes when connected; without Cloud, use local `team-sync handoff` or `final-commit` for OSS continuity
 - `snipara-companion memory-guard check` = forced memory/context recall before retries, commits, or finalization when a command failed or a publishable package surface is touched
 - `snipara-companion memory-guard check --intent "<action>" --destructive --strict` = contradiction check before irreversible actions; blocks until the user explicitly confirms when memory/context disagrees or the action is destructive
 - `snipara-companion memory-guard remember --guard-tag pre-commit --text "..."` = create a project/team memory in a guard category such as `pre-commit`, `commit`, `failure`, `pre-final`, or `workflow-policy`
@@ -835,8 +895,7 @@ or `unchanged` counts until a real sync runs.
 For release-hardening and local packaging checks:
 
 ```bash
-pnpm --filter snipara-companion pack:smoke
-pnpm --filter create-snipara pack:smoke
+pnpm pack:smoke
 ```
 
 To test a packed tarball manually, use `npm exec --package`:

package/dist/index.d.ts

@@ -1077,6 +1077,50 @@ declare function detectReleaseSurfacesFromFiles(root: string, files: string[]):
 declare function getStagedFiles(root: string): string[];
 declare function runMemoryGuardCheck(options?: MemoryGuardCheckOptions): Promise<MemoryGuardCheckResult>;
 
+interface GitCompanionSummaryOptions {
+    cwd?: string;
+    recentLimit?: number;
+}
+interface GitCompanionSummary {
+    version: "snipara.git_companion.v1";
+    generatedAt: string;
+    repository?: {
+        root: string;
+        branch?: string;
+        head?: string;
+        upstream?: string;
+        ahead?: number;
+        behind?: number;
+    };
+    status: {
+        clean: boolean;
+        total: number;
+        staged: string[];
+        unstaged: string[];
+        untracked: string[];
+        conflicted: string[];
+        lines: string[];
+    };
+    recentCommits: Array<{
+        sha: string;
+        shortSha: string;
+        author: string;
+        date: string;
+        subject: string;
+    }>;
+    hosted: {
+        status: "not_required";
+        note: string;
+    };
+    suggestedCommands: string[];
+    error?: string;
+}
+declare function buildGitCompanionSummary(options?: GitCompanionSummaryOptions): GitCompanionSummary;
+declare function gitSummaryCommand(options: {
+    recent?: number;
+    json?: boolean;
+}): Promise<void>;
+
 interface ProjectIntelligenceBriefOptions {
     task?: string;
     branch?: string;
@@ -1091,6 +1135,7 @@ interface ProjectIntelligenceBriefOptions {
 interface ProjectIntelligenceBrief {
     version: "project-intelligence-brief-v1";
     generatedAt: string;
+    provider: "hosted" | "local";
     branch?: string;
     task?: string;
     changedFiles: string[];
@@ -1098,6 +1143,8 @@ interface ProjectIntelligenceBrief {
     resumeContext?: Record<string, unknown>;
     memoryHealth?: Record<string, unknown>;
     codeImpact?: Record<string, unknown>;
+    localMemory?: RecallResult;
+    hosted?: Record<string, unknown>;
     errors: Array<{
         surface: string;
         message: string;
@@ -2147,4 +2194,4 @@ interface WrittenOrchestratorHandoff {
 declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, 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, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, 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, buildGitCompanionSummary, buildHostedCodeOverlayUploadPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collectSyncDocuments, collectSyncDocumentsInput, createClient, createEmptyTeamSyncState, createLocalQueryCache, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, gitSummaryCommand, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, normalizeGuardTag, normalizeWorkflowPlanInput, projectIntelligenceBriefCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveQueryFromToolInput, runMemoryGuardCheck, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };