@tricknowtech/context 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,34 @@
+/**
+ * Per-assistant knowledge of where context lives.
+ *
+ * Every coding assistant keeps two kinds of state: instruction files inside
+ * the repo (which git may or may not already carry), and user-global config
+ * in the home directory (which never travels). The adapter's job is to name
+ * both, so the collector stays assistant-agnostic.
+ *
+ * Adding support for a new tool means adding one entry here — nothing in the
+ * collector, store, or CLI needs to change.
+ */
+interface UserFile {
+    /** Absolute path on this machine. */
+    abs: string;
+    /** Path within the assistant's namespace in the store, e.g. `memory/note.md`. */
+    rel: string;
+}
+interface AssistantAdapter {
+    id: string;
+    name: string;
+    /**
+     * Project-relative globs this assistant owns. Files matching these are
+     * collected unless git already tracks them.
+     */
+    projectGlobs: string[];
+    /** Home-relative directory used to detect whether the tool is installed. */
+    userDir?: (home: string) => string;
+    /** User-global files worth carrying, resolved per project. */
+    collectUser?: (projectRoot: string, home: string, exclude: string[]) => UserFile[];
+}
+
 /** Root of the user's global Claude directory (~/.claude), overridable for tests. */
 declare function userClaudeDir(): string;
 /**
@@ -21,6 +52,8 @@ interface TemplateContext {
     userClaude: string;
     project: string;
     cwdKey: string;
+    /** The user's home directory — how non-Claude assistants (~/.codex, ~/.gemini) template. */
+    home: string;
 }
 declare function makeTemplate(absPath: string, ctx: TemplateContext): string;
 declare function resolveTemplate(template: string, ctx: TemplateContext): string;
@@ -101,6 +134,11 @@ interface ProjectConfig {
      */
     rootHint: string;
     tiers: Tier[];
+    /**
+     * Assistant ids to sync (`claude`, `codex`, `cursor`, …), or `['auto']` to
+     * detect from what is installed and what the repo already contains.
+     */
+    assistants: string[];
     /** Extra project-relative dirs to capture as `artifacts`. */
     artifactPaths: string[];
     /** Glob-ish patterns excluded from collection, on top of the hard-coded denylist. */
@@ -140,26 +178,65 @@ interface CollectResult {
     files: CollectedFile[];
     /** Project files skipped because git already carries them. */
     skippedTracked: string[];
+    /** Assistants this project was found to use. */
+    assistants: AssistantAdapter[];
     ctx: TemplateContext;
 }
 /**
- * Decide what constitutes this project's LLM context.
+ * Decide what constitutes this project's LLM context, across every assistant
+ * in use.
  *
- * Two roots are scanned, and they are treated very differently:
+ * Two roots are treated very differently:
  *
  *  - **The project itself** — anything git already tracks is *skipped*. It
- *    travels with the code, so copying it into the store would duplicate it
- *    and create a second copy that silently drifts out of date.
- *  - **The user's global Claude directory** — this is the real payload. The
- *    per-project memory, skills, and global instructions live outside the
- *    repo and are exactly what never makes it to a second machine today.
+ *    travels with the code, so copying it in would create a second copy that
+ *    silently drifts.
+ *  - **The user's home directory** — this is the real payload. Per-project
+ *    memory, skills, prompts and global instructions live outside the repo and
+ *    are exactly what never reaches a second machine today.
  */
 declare function collect(projectRoot: string, cfg: ProjectConfig, tiers: Tier[]): CollectResult;
+interface ExcludedGroup {
+    label: string;
+    files: number;
+    bytes: number;
+    reason: string;
+}
+/**
+ * What was deliberately left behind, and why.
+ *
+ * Without this a user sees "17 files synced" against a ~400 MB context
+ * directory and reasonably concludes the tool is broken. Naming the omissions
+ * — with sizes — is the difference between a considered exclusion and a
+ * silent one.
+ */
+declare function describeExcluded(projectRoot: string, tiers: Tier[]): ExcludedGroup[];
 declare function summarize(files: CollectedFile[]): Record<Tier, {
     count: number;
     bytes: number;
 }>;
 
+/**
+ * The handoff is the whole point of the tool — files alone tell you what a
+ * project knows, but not where you stopped. It is written by the model (only
+ * it has the conversation) and read back on the other machine.
+ *
+ * Because a model writes it, it needs real validation: a silently malformed
+ * handoff is worse than none, since `pull` would look like it worked while
+ * handing back nothing usable.
+ */
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    handoff?: Handoff;
+}
+declare function validateHandoff(raw: unknown): ValidationResult;
+/** Render a handoff for a human picking the work back up. */
+declare function formatHandoff(h: Handoff): string[];
+declare function handoffAge(h: Handoff): string;
+/** True when the handoff predates the newest synced content by a wide margin. */
+declare function isStale(h: Handoff, newestContentMs: number): boolean;
+
 declare const STORE_DIR = ".contextsync";
 declare const CONFIG_FILE = "config.json";
 declare const HANDOFF_FILE = "handoff.json";
@@ -266,4 +343,4 @@ declare class LocalStore implements Store {
     writeHandoff(handoff: Handoff): void;
 }
 
-export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, collect, configPath, cwdKey, defaultConfig, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHits, gitTrackedSet, installSlashCommand, isGitRepo, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, walk };
+export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, type ExcludedGroup, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, type ValidationResult, collect, configPath, cwdKey, defaultConfig, describeExcluded, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHandoff, formatHits, gitTrackedSet, handoffAge, installSlashCommand, isGitRepo, isStale, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, validateHandoff, walk };

package/dist/index.d.ts

@@ -1,3 +1,34 @@
+/**
+ * Per-assistant knowledge of where context lives.
+ *
+ * Every coding assistant keeps two kinds of state: instruction files inside
+ * the repo (which git may or may not already carry), and user-global config
+ * in the home directory (which never travels). The adapter's job is to name
+ * both, so the collector stays assistant-agnostic.
+ *
+ * Adding support for a new tool means adding one entry here — nothing in the
+ * collector, store, or CLI needs to change.
+ */
+interface UserFile {
+    /** Absolute path on this machine. */
+    abs: string;
+    /** Path within the assistant's namespace in the store, e.g. `memory/note.md`. */
+    rel: string;
+}
+interface AssistantAdapter {
+    id: string;
+    name: string;
+    /**
+     * Project-relative globs this assistant owns. Files matching these are
+     * collected unless git already tracks them.
+     */
+    projectGlobs: string[];
+    /** Home-relative directory used to detect whether the tool is installed. */
+    userDir?: (home: string) => string;
+    /** User-global files worth carrying, resolved per project. */
+    collectUser?: (projectRoot: string, home: string, exclude: string[]) => UserFile[];
+}
+
 /** Root of the user's global Claude directory (~/.claude), overridable for tests. */
 declare function userClaudeDir(): string;
 /**
@@ -21,6 +52,8 @@ interface TemplateContext {
     userClaude: string;
     project: string;
     cwdKey: string;
+    /** The user's home directory — how non-Claude assistants (~/.codex, ~/.gemini) template. */
+    home: string;
 }
 declare function makeTemplate(absPath: string, ctx: TemplateContext): string;
 declare function resolveTemplate(template: string, ctx: TemplateContext): string;
@@ -101,6 +134,11 @@ interface ProjectConfig {
      */
     rootHint: string;
     tiers: Tier[];
+    /**
+     * Assistant ids to sync (`claude`, `codex`, `cursor`, …), or `['auto']` to
+     * detect from what is installed and what the repo already contains.
+     */
+    assistants: string[];
     /** Extra project-relative dirs to capture as `artifacts`. */
     artifactPaths: string[];
     /** Glob-ish patterns excluded from collection, on top of the hard-coded denylist. */
@@ -140,26 +178,65 @@ interface CollectResult {
     files: CollectedFile[];
     /** Project files skipped because git already carries them. */
     skippedTracked: string[];
+    /** Assistants this project was found to use. */
+    assistants: AssistantAdapter[];
     ctx: TemplateContext;
 }
 /**
- * Decide what constitutes this project's LLM context.
+ * Decide what constitutes this project's LLM context, across every assistant
+ * in use.
  *
- * Two roots are scanned, and they are treated very differently:
+ * Two roots are treated very differently:
  *
  *  - **The project itself** — anything git already tracks is *skipped*. It
- *    travels with the code, so copying it into the store would duplicate it
- *    and create a second copy that silently drifts out of date.
- *  - **The user's global Claude directory** — this is the real payload. The
- *    per-project memory, skills, and global instructions live outside the
- *    repo and are exactly what never makes it to a second machine today.
+ *    travels with the code, so copying it in would create a second copy that
+ *    silently drifts.
+ *  - **The user's home directory** — this is the real payload. Per-project
+ *    memory, skills, prompts and global instructions live outside the repo and
+ *    are exactly what never reaches a second machine today.
  */
 declare function collect(projectRoot: string, cfg: ProjectConfig, tiers: Tier[]): CollectResult;
+interface ExcludedGroup {
+    label: string;
+    files: number;
+    bytes: number;
+    reason: string;
+}
+/**
+ * What was deliberately left behind, and why.
+ *
+ * Without this a user sees "17 files synced" against a ~400 MB context
+ * directory and reasonably concludes the tool is broken. Naming the omissions
+ * — with sizes — is the difference between a considered exclusion and a
+ * silent one.
+ */
+declare function describeExcluded(projectRoot: string, tiers: Tier[]): ExcludedGroup[];
 declare function summarize(files: CollectedFile[]): Record<Tier, {
     count: number;
     bytes: number;
 }>;
 
+/**
+ * The handoff is the whole point of the tool — files alone tell you what a
+ * project knows, but not where you stopped. It is written by the model (only
+ * it has the conversation) and read back on the other machine.
+ *
+ * Because a model writes it, it needs real validation: a silently malformed
+ * handoff is worse than none, since `pull` would look like it worked while
+ * handing back nothing usable.
+ */
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    handoff?: Handoff;
+}
+declare function validateHandoff(raw: unknown): ValidationResult;
+/** Render a handoff for a human picking the work back up. */
+declare function formatHandoff(h: Handoff): string[];
+declare function handoffAge(h: Handoff): string;
+/** True when the handoff predates the newest synced content by a wide margin. */
+declare function isStale(h: Handoff, newestContentMs: number): boolean;
+
 declare const STORE_DIR = ".contextsync";
 declare const CONFIG_FILE = "config.json";
 declare const HANDOFF_FILE = "handoff.json";
@@ -266,4 +343,4 @@ declare class LocalStore implements Store {
     writeHandoff(handoff: Handoff): void;
 }
 
-export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, collect, configPath, cwdKey, defaultConfig, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHits, gitTrackedSet, installSlashCommand, isGitRepo, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, walk };
+export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, type ExcludedGroup, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, type ValidationResult, collect, configPath, cwdKey, defaultConfig, describeExcluded, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHandoff, formatHits, gitTrackedSet, handoffAge, installSlashCommand, isGitRepo, isStale, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, validateHandoff, walk };

package/dist/index.js

@@ -14,13 +14,17 @@ import {
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
   gitTrackedSet,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
   makeTemplate,
   matchesAny,
@@ -30,8 +34,9 @@ import {
   storeDir,
   summarize,
   userClaudeDir,
+  validateHandoff,
   walk
-} from "./chunk-BWATZKYM.js";
+} from "./chunk-BLEGQVXA.js";
 export {
   ALL_TIERS,
   CONFIG_FILE,
@@ -48,13 +53,17 @@ export {
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
   gitTrackedSet,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
   makeTemplate,
   matchesAny,
@@ -64,5 +73,6 @@ export {
   storeDir,
   summarize,
   userClaudeDir,
+  validateHandoff,
   walk
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tricknowtech/context",
-  "version": "0.1.1",
-  "description": "Carry a project's LLM context — memory, skills, instructions and session handoff — between machines. Local-first, commit it to your repo.",
+  "version": "0.3.0",
+  "description": "Carry a project's LLM context between machines \u2014 Claude Code, Codex, Cursor, Copilot, Gemini, Windsurf, Cline, Aider. Local-first, commit it to your repo.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -32,9 +32,17 @@
     "llm",
     "context",
     "claude",
+    "codex",
+    "cursor",
+    "copilot",
+    "gemini",
+    "windsurf",
+    "aider",
+    "cline",
     "ai",
     "sync",
-    "memory"
+    "memory",
+    "agents-md"
   ],
   "author": "Tricknowtech",
   "license": "ISC",