@vortex-os/base 0.2.3 → 0.3.0

package/README.md

@@ -18,7 +18,40 @@ Base entry point for **VortEX** — a Multi-Agent Personal AI Work OS framework.
 npm install @vortex-os/base
 ```
 
-## Usage
+## Quick start — one install, then `init`
+
+`@vortex-os/base` ships a `vortex` CLI, so a working instance is three steps:
+
+```bash
+npm install @vortex-os/base     # install the framework into a new folder
+npx vortex init                 # scaffold the instance (asks for name / role / task)
+# then open your agent (e.g. `claude`) in that folder
+```
+
+`npx vortex init` is non-destructive and creates, in the current folder:
+
+- the five per-agent router files — `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules` — so any agent host finds VortEX's behavior contract (these are generic templates you personalize over time);
+- the `data/` skeleton (`_memory/`, `worklog/`, `decision-log/`, `runbooks/`, `hubs/`, `inbox/`), your user-profile memory, and today's first worklog;
+- `.claude/settings.json` with the session hooks wired as `npx --no-install -p @vortex-os/base vortex session-start` / `… session-end` (the `--no-install` flag and explicit `-p` package make the auto-firing hook fail closed rather than install or shadow), plus the agent-mediated slash-commands in `.claude/commands/`;
+- `.agent/vortex.json` (auto-record config) and a minimal `package.json` with `"type":"module"` if none exists.
+
+Pass the answers inline to skip the prompts:
+
+```bash
+npx vortex init --name "Alex" --role "engineer" --task "set up my work notes"
+```
+
+Other CLI entry points (all run base-only — `/recall` lights up only when the optional add-on is installed):
+
+```bash
+npx vortex --list           # list available commands
+npx vortex status           # instance state report
+npx vortex session-start    # start-of-session boot report (git pull + counts + catch-up)
+npx vortex session-end      # worklog safety net
+npx vortex doctor           # health diagnosis
+```
+
+## Library usage
 
 ```ts
 import {
@@ -95,6 +128,11 @@ Future capability clusters publish as siblings under the `@vortex-os` scope and
 
 Each add-on installs alongside the base and extends what the agent can do without forcing a base upgrade.
 
+## Privacy & network behavior
+
+- **`vortex init` folder scan.** To suggest content you might want to import, `init` does a read-only scan for common notes-folder names (e.g. an Obsidian vault, a `notes/` directory) under your home directory. It only reads directory listings to count Markdown files and surface a hint — it never copies, modifies, or transmits anything. Import happens only when you explicitly run `vortex import --from <path>`.
+- **No network calls in the base.** Base itself makes no outbound network requests. The optional `@vortex-os/memory-extended` add-on, when installed, may download an embedding model (read-only `GET` from `huggingface.co`, cacheable / offline-able via `HF_HUB_OFFLINE=1`) and feeds transcript excerpts to whatever LLM adapter you wire into its consolidation step. See that package's README for details.
+
 ## Packaging notes
 
 - **Bundled**: all 14 workspaces are bundled into the published artifact via `tsup`. Consumers do not need to install workspace packages individually.

package/bin/vortex.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// `vortex` — the CLI shipped by @vortex-os/base.
+//
+// `npm i @vortex-os/base` puts this on the instance's path (node_modules/.bin),
+// so `npx vortex init` / `npx vortex session-start` / `npx vortex --list` work
+// without any monorepo checkout. It is a thin wrapper over the canonical
+// dispatch (`runVortexCli`), which is bundled into base from
+// `@vortex-os/session-rituals` — exactly one source of truth for the CLI logic.
+//
+// The dispatch lazily probes the optional `@vortex-os/memory-extended` add-on:
+// when it is installed alongside base, `/recall` lights up; on a lean base-only
+// install the probe is caught and the CLI runs with every other command.
+
+import { sessionRituals } from "../dist/index.js";
+
+const code = await sessionRituals.runVortexCli(process.argv.slice(2));
+process.exitCode = code;

package/dist/catch-up-ZQN7HMMN.js

@@ -0,0 +1,7 @@
+import {
+  catchUpSessions
+} from "./chunk-6SO4DAWJ.js";
+export {
+  catchUpSessions
+};
+//# sourceMappingURL=catch-up-ZQN7HMMN.js.map

package/dist/catch-up-ZQN7HMMN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-6SO4DAWJ.js

@@ -0,0 +1,32 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// ../plugins/session-rituals/dist/catch-up.js
+async function catchUpSessions(ctx, opts) {
+  const { sessionArchive } = await import("@vortex-os/memory-extended");
+  const dataDir = ctx.dataDir;
+  const cwd = opts?.cwd ?? ctx.repoRoot;
+  const adapters = opts?.adapters ?? [sessionArchive.claudeCodeAdapter];
+  const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });
+  const store = new sessionArchive.SessionArchiveStore(dataDir);
+  let indexedPulled = 0;
+  try {
+    indexedPulled = store.reindexFromNormalized().indexed;
+  } finally {
+    store.close();
+  }
+  return {
+    ingestedLocal: ingestResult.sessionsIngested,
+    indexedPulled,
+    errors: ingestResult.errors.length
+  };
+}
+
+export {
+  __export,
+  catchUpSessions
+};
+//# sourceMappingURL=chunk-6SO4DAWJ.js.map

package/dist/chunk-6SO4DAWJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../plugins/session-rituals/src/catch-up.ts"],"sourcesContent":["import type { ModuleContext } from \"@vortex-os/core\";\n// Type-only — erased at compile time, so importing it does NOT pull the\n// `@vortex-os/memory-extended` add-on (or its native sqlite/level deps) into\n// the module graph of consumers that only need the types. The runtime engine\n// is loaded lazily inside the function body via `await import(...)`.\nimport type { sessionArchive } from \"@vortex-os/memory-extended\";\n\n/**\n * Start-of-session \"catch-up\": fold conversation transcripts into the local\n * search archive without the user ever having to wrap up a session.\n *\n * Two sources, one pass:\n *  - **local (a)** — this machine's own transcripts that are not archived yet,\n *    read from the agent's transcript store and scoped to the current project.\n *  - **pulled (b)** — transcripts created on another machine that arrived as\n *    normalized text via git sync. Their text is present but this machine's\n *    DB (local, derived, gitignored) has never indexed them.\n *\n * Text only — vectorization is deferred to recall/rebuild so session start\n * stays fast. The whole step is gated by `autoRecord.archive` at the call site\n * and is best-effort: callers should treat a thrown archive backend (e.g. the\n * native sqlite module not built) as \"skip\", never as a fatal start error.\n */\nexport interface CatchUpResult {\n  /** Local transcripts newly archived this run (source a). */\n  readonly ingestedLocal: number;\n  /** Normalized transcripts from another machine newly indexed (source b). */\n  readonly indexedPulled: number;\n  /** Per-session ingest errors (source a). */\n  readonly errors: number;\n}\n\nexport interface CatchUpOptions {\n  /** Restrict local ingest to one project's transcripts. Default: `ctx.repoRoot`. */\n  readonly cwd?: string;\n  /**\n   * Transcript adapters for local ingest. Default: Claude Code only. Other\n   * hosts (Codex, Gemini) can be added by a caller; tests inject fakes so the\n   * scan never touches the real home directory.\n   */\n  readonly adapters?: sessionArchive.IngestParams[\"adapters\"];\n  /** Adapter environment override (e.g. a sandbox HOME). Tests use this. */\n  readonly env?: sessionArchive.IngestParams[\"env\"];\n}\n\nexport async function catchUpSessions(\n  ctx: ModuleContext,\n  opts?: CatchUpOptions,\n): Promise<CatchUpResult> {\n  // Lazy-load the optional add-on. Base ships without `memory-extended`; this\n  // import resolves only when the add-on is installed alongside it. The call\n  // site already gates this step on `autoRecord.archive` and treats a thrown\n  // backend as \"skip\", so a missing add-on surfaces as a normal load error\n  // the caller can catch.\n  const { sessionArchive } = await import(\"@vortex-os/memory-extended\");\n\n  const dataDir = ctx.dataDir;\n  const cwd = opts?.cwd ?? ctx.repoRoot;\n  const adapters = opts?.adapters ?? [sessionArchive.claudeCodeAdapter];\n\n  // (a) Ingest this machine's not-yet-archived transcripts for the current\n  // project. Writes the normalized copy into the archive (which git syncs) and\n  // a local DB row. Text only — no vectorization here.\n  const ingestResult = await sessionArchive.ingest({ adapters, dataDir, cwd, env: opts?.env });\n\n  // (b) Index normalized transcripts that arrived from another machine via git\n  // pull — their text is on disk but this machine's DB has no row yet.\n  const store = new sessionArchive.SessionArchiveStore(dataDir);\n  let indexedPulled = 0;\n  try {\n    indexedPulled = store.reindexFromNormalized().indexed;\n  } finally {\n    store.close();\n  }\n\n  return {\n    ingestedLocal: ingestResult.sessionsIngested,\n    indexedPulled,\n    errors: ingestResult.errors.length,\n  };\n}\n"],"mappings":";;;;;;;AA6CA,eAAsB,gBACpB,KACA,MAAqB;AAOrB,QAAM,EAAE,eAAc,IAAK,MAAM,OAAO,4BAA4B;AAEpE,QAAM,UAAU,IAAI;AACpB,QAAM,MAAM,MAAM,OAAO,IAAI;AAC7B,QAAM,WAAW,MAAM,YAAY,CAAC,eAAe,iBAAiB;AAKpE,QAAM,eAAe,MAAM,eAAe,OAAO,EAAE,UAAU,SAAS,KAAK,KAAK,MAAM,IAAG,CAAE;AAI3F,QAAM,QAAQ,IAAI,eAAe,oBAAoB,OAAO;AAC5D,MAAI,gBAAgB;AACpB,MAAI;AACF,oBAAgB,MAAM,sBAAqB,EAAG;EAChD;AACE,UAAM,MAAK;EACb;AAEA,SAAO;IACL,eAAe,aAAa;IAC5B;IACA,QAAQ,aAAa,OAAO;;AAEhC;","names":[]}

package/dist/index.d.ts

@@ -2369,6 +2369,32 @@ interface RitualRegistryOptions {
  */
 declare function createRitualRegistry(options?: RitualRegistryOptions): CommandRegistry;
 
+interface CliIo {
+    /** Write a chunk to stdout. Default: `process.stdout.write`. */
+    readonly stdout?: (s: string) => void;
+    /** Write a chunk to stderr. Default: `process.stderr.write`. */
+    readonly stderr?: (s: string) => void;
+}
+/**
+ * Build the ritual registry, lighting up `/recall` ONLY when the optional
+ * `@vortex-os/memory-extended` add-on is installed alongside base.
+ *
+ * Base ships without the add-on (it is `external` in the tsup bundle), so this
+ * probe is a real `await import` that throws `ERR_MODULE_NOT_FOUND` on a lean
+ * install — caught here so the CLI runs with base alone and never throws on
+ * startup. When the add-on IS present, its local embedder wires up `/recall`.
+ * `curate` is intentionally NOT wired here — it is agent-mediated.
+ */
+declare function buildRegistry(): Promise<CommandRegistry>;
+/** Resolve the repo root the same way every entry point should: env override, else cwd. */
+declare function resolveRepoRoot(): string;
+/**
+ * Run the `vortex` CLI for the given argv (already sliced past `node script`).
+ * Returns the process exit code (0 success, 1 on error) instead of calling
+ * `process.exit`, so callers/tests stay in control.
+ */
+declare function runVortexCli(argv: readonly string[], io?: CliIo): Promise<number>;
+
 /**
  * Bridge the `@vortex-os/memory-extended` recall engine into a
  * `@vortex-os/proactive-curator` {@link AmbientRecaller} — defined in the
@@ -2561,8 +2587,8 @@ declare function catchUpSessions(ctx: ModuleContext, opts?: CatchUpOptions): Pro
  * file read/write around them. Keeping them pure makes the merge unit-testable
  * and the "writes only what's missing" guarantee verifiable.
  */
-declare const SESSION_START_COMMAND = "node plugins/session-rituals/scripts/session-start-hook.mjs";
-declare const SESSION_END_COMMAND = "node plugins/session-rituals/scripts/session-end-hook.mjs";
+declare const SESSION_START_COMMAND = "npx --no-install -p @vortex-os/base vortex session-start";
+declare const SESSION_END_COMMAND = "npx --no-install -p @vortex-os/base vortex session-end";
 interface HookCommand {
     readonly type: "command";
     readonly command: string;
@@ -2914,6 +2940,7 @@ type index_d_AmbientRecallFactoryOptions = AmbientRecallFactoryOptions;
 type index_d_CatchUpOptions = CatchUpOptions;
 type index_d_CatchUpResult = CatchUpResult;
 type index_d_ClaudeSettings = ClaudeSettings;
+type index_d_CliIo = CliIo;
 type index_d_CollectAgendaOptions = CollectAgendaOptions;
 type index_d_CurateAnyProposal = CurateAnyProposal;
 type index_d_CurateOptions = CurateOptions;
@@ -2942,6 +2969,7 @@ type index_d_VortexSyncStepId = VortexSyncStepId;
 type index_d_VortexSyncStepStatus = VortexSyncStepStatus;
 type index_d_WorklogAppendResult = WorklogAppendResult;
 declare const index_d_agendaCommand: typeof agendaCommand;
+declare const index_d_buildRegistry: typeof buildRegistry;
 declare const index_d_catchUpSessions: typeof catchUpSessions;
 declare const index_d_collectAgenda: typeof collectAgenda;
 declare const index_d_collectSessionStartReport: typeof collectSessionStartReport;
@@ -2960,11 +2988,13 @@ declare const index_d_recallCommand: typeof recallCommand;
 declare const index_d_reindexCommand: typeof reindexCommand;
 declare const index_d_renderAgenda: typeof renderAgenda;
 declare const index_d_renderSessionStartReport: typeof renderSessionStartReport;
+declare const index_d_resolveRepoRoot: typeof resolveRepoRoot;
+declare const index_d_runVortexCli: typeof runVortexCli;
 declare const index_d_serializeSettings: typeof serializeSettings;
 declare const index_d_sessionStartCommand: typeof sessionStartCommand;
 declare const index_d_vortexCommand: typeof vortexCommand;
 declare namespace index_d {
-  export { type index_d_AgendaReport as AgendaReport, type index_d_AmbientRecallFactoryOptions as AmbientRecallFactoryOptions, type index_d_CatchUpOptions as CatchUpOptions, type index_d_CatchUpResult as CatchUpResult, type index_d_ClaudeSettings as ClaudeSettings, type index_d_CollectAgendaOptions as CollectAgendaOptions, type index_d_CurateAnyProposal as CurateAnyProposal, type index_d_CurateOptions as CurateOptions, type index_d_CurateResult as CurateResult, type index_d_EnsureHooksResult as EnsureHooksResult, type index_d_EnsureWorklogResult as EnsureWorklogResult, type index_d_GitPullResult as GitPullResult, type index_d_NewDecisionResult as NewDecisionResult, type index_d_OpenDecision as OpenDecision, type index_d_OpenTask as OpenTask, type index_d_RecallOptions as RecallOptions, type index_d_RecentWorklog as RecentWorklog, type index_d_ReindexResult as ReindexResult, type index_d_RitualRegistryOptions as RitualRegistryOptions, index_d_SESSION_END_COMMAND as SESSION_END_COMMAND, index_d_SESSION_START_COMMAND as SESSION_START_COMMAND, type index_d_SessionStartHookReport as SessionStartHookReport, type index_d_SessionStartReport as SessionStartReport, type index_d_VortexHelpResult as VortexHelpResult, type index_d_VortexInitResult as VortexInitResult, type index_d_VortexPlannedResult as VortexPlannedResult, type index_d_VortexResult as VortexResult, type index_d_VortexSyncResult as VortexSyncResult, type index_d_VortexSyncStep as VortexSyncStep, type index_d_VortexSyncStepId as VortexSyncStepId, type index_d_VortexSyncStepStatus as VortexSyncStepStatus, type index_d_WorklogAppendResult as WorklogAppendResult, index_d_agendaCommand as agendaCommand, index_d_catchUpSessions as catchUpSessions, index_d_collectAgenda as collectAgenda, index_d_collectSessionStartReport as collectSessionStartReport, index_d_createAmbientRecaller as createAmbientRecaller, index_d_createRitualRegistry as createRitualRegistry, index_d_curateCommand as curateCommand, index_d_decisionCommand as decisionCommand, index_d_detectWorklogGaps as detectWorklogGaps, index_d_ensureVortexHooks as ensureVortexHooks, index_d_ensureWorklogEntry as ensureWorklogEntry, index_d_extractNextUp as extractNextUp, index_d_extractOpenTasks as extractOpenTasks, index_d_logCommand as logCommand, index_d_parseSettings as parseSettings, index_d_recallCommand as recallCommand, index_d_reindexCommand as reindexCommand, index_d_renderAgenda as renderAgenda, index_d_renderSessionStartReport as renderSessionStartReport, index_d_serializeSettings as serializeSettings, index_d_sessionStartCommand as sessionStartCommand, index_d_vortexCommand as vortexCommand };
+  export { type index_d_AgendaReport as AgendaReport, type index_d_AmbientRecallFactoryOptions as AmbientRecallFactoryOptions, type index_d_CatchUpOptions as CatchUpOptions, type index_d_CatchUpResult as CatchUpResult, type index_d_ClaudeSettings as ClaudeSettings, type index_d_CliIo as CliIo, type index_d_CollectAgendaOptions as CollectAgendaOptions, type index_d_CurateAnyProposal as CurateAnyProposal, type index_d_CurateOptions as CurateOptions, type index_d_CurateResult as CurateResult, type index_d_EnsureHooksResult as EnsureHooksResult, type index_d_EnsureWorklogResult as EnsureWorklogResult, type index_d_GitPullResult as GitPullResult, type index_d_NewDecisionResult as NewDecisionResult, type index_d_OpenDecision as OpenDecision, type index_d_OpenTask as OpenTask, type index_d_RecallOptions as RecallOptions, type index_d_RecentWorklog as RecentWorklog, type index_d_ReindexResult as ReindexResult, type index_d_RitualRegistryOptions as RitualRegistryOptions, index_d_SESSION_END_COMMAND as SESSION_END_COMMAND, index_d_SESSION_START_COMMAND as SESSION_START_COMMAND, type index_d_SessionStartHookReport as SessionStartHookReport, type index_d_SessionStartReport as SessionStartReport, type index_d_VortexHelpResult as VortexHelpResult, type index_d_VortexInitResult as VortexInitResult, type index_d_VortexPlannedResult as VortexPlannedResult, type index_d_VortexResult as VortexResult, type index_d_VortexSyncResult as VortexSyncResult, type index_d_VortexSyncStep as VortexSyncStep, type index_d_VortexSyncStepId as VortexSyncStepId, type index_d_VortexSyncStepStatus as VortexSyncStepStatus, type index_d_WorklogAppendResult as WorklogAppendResult, index_d_agendaCommand as agendaCommand, index_d_buildRegistry as buildRegistry, index_d_catchUpSessions as catchUpSessions, index_d_collectAgenda as collectAgenda, index_d_collectSessionStartReport as collectSessionStartReport, index_d_createAmbientRecaller as createAmbientRecaller, index_d_createRitualRegistry as createRitualRegistry, index_d_curateCommand as curateCommand, index_d_decisionCommand as decisionCommand, index_d_detectWorklogGaps as detectWorklogGaps, index_d_ensureVortexHooks as ensureVortexHooks, index_d_ensureWorklogEntry as ensureWorklogEntry, index_d_extractNextUp as extractNextUp, index_d_extractOpenTasks as extractOpenTasks, index_d_logCommand as logCommand, index_d_parseSettings as parseSettings, index_d_recallCommand as recallCommand, index_d_reindexCommand as reindexCommand, index_d_renderAgenda as renderAgenda, index_d_renderSessionStartReport as renderSessionStartReport, index_d_resolveRepoRoot as resolveRepoRoot, index_d_runVortexCli as runVortexCli, index_d_serializeSettings as serializeSettings, index_d_sessionStartCommand as sessionStartCommand, index_d_vortexCommand as vortexCommand };
 }
 
 export { index_d$9 as aiCodingPitfalls, index_d$d as core, index_d$a as dataLint, index_d$5 as decisionLog, index_d$4 as indexGenerator, index_d$2 as linkRewriter, index_d$b as memorySystem, index_d$1 as proactiveCurator, index_d$7 as reportGenerator, index_d$3 as runbooks, index_d as sessionRituals, index_d$c as slashCommands, index_d$8 as toolRules, index_d$6 as worklog };