@remnic/core 1.1.2 → 1.1.4

package/dist/chunk-OA3L7BFR.js

@@ -0,0 +1,183 @@
+// src/transfer/types.ts
+import { z } from "zod";
+var ExportManifestV1Schema = z.object({
+  format: z.literal("openclaw-engram-export"),
+  schemaVersion: z.literal(1),
+  createdAt: z.string(),
+  pluginVersion: z.string(),
+  includesTranscripts: z.boolean(),
+  files: z.array(
+    z.object({
+      path: z.string(),
+      sha256: z.string(),
+      bytes: z.number().int().nonnegative()
+    })
+  )
+});
+var ExportMemoryRecordV1Schema = z.object({
+  path: z.string(),
+  content: z.string()
+});
+var ExportBundleV1Schema = z.object({
+  manifest: ExportManifestV1Schema,
+  records: z.array(ExportMemoryRecordV1Schema)
+});
+var CAPSULE_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?!-))*[A-Za-z0-9]$|^[A-Za-z0-9]$/;
+var CapsuleIdSchema = z.string().min(1, "capsule.id must not be empty").max(64, "capsule.id must be 64 characters or fewer").regex(
+  CAPSULE_ID_PATTERN,
+  "capsule.id must be alphanumeric with single dashes (no spaces, no leading/trailing dashes)"
+);
+var SemverLikeSchema = z.string().min(1, "capsule.version must not be empty").regex(
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/,
+  "capsule.version must be a semver-like string (e.g. 1.0.0)"
+);
+var CapsuleRetrievalPolicySchema = z.object({
+  /**
+   * Per-tier weight overrides applied during recall when the capsule is the
+   * active scope. Keys are tier names (e.g. `bm25`, `vector`, `graph`); values
+   * are non-negative finite multipliers. The set of valid keys is left open
+   * for now so future tiers do not break older manifests.
+   */
+  tierWeights: z.record(
+    z.string().min(1),
+    z.number().finite().nonnegative()
+  ),
+  /**
+   * Whether the direct-answer fast path is allowed when this capsule is
+   * active. Operators may disable it for capsules whose contents should
+   * always flow through the full retrieval pipeline.
+   */
+  directAnswerEnabled: z.boolean()
+});
+var CapsuleIncludesSchema = z.object({
+  taxonomy: z.boolean(),
+  identityAnchors: z.boolean(),
+  peerProfiles: z.boolean(),
+  procedural: z.boolean()
+});
+var CapsuleParentSchema = z.object({
+  capsuleId: CapsuleIdSchema,
+  version: SemverLikeSchema,
+  /**
+   * Posix-relative path prefix under the fork's memory root where the parent
+   * capsule's records were placed. Typically `forks/<parent-capsule-id>`.
+   * Must be a non-empty string with no leading slash.
+   */
+  forkRoot: z.string().min(1, "capsule.parent.forkRoot must not be empty").refine((v) => !v.startsWith("/"), {
+    message: "capsule.parent.forkRoot must be a relative path (no leading slash)"
+  })
+});
+var CapsuleBlockSchema = z.object({
+  id: CapsuleIdSchema,
+  version: SemverLikeSchema,
+  /**
+   * Taxonomy schema version the capsule was authored against. Free-form for
+   * now; later PRs may tighten this to a known taxonomy registry.
+   */
+  schemaVersion: z.string().min(1, "capsule.schemaVersion must not be empty"),
+  /**
+   * Optional reference to the parent capsule this one was forked or derived
+   * from. `null` (not `undefined`) is the explicit "no parent" sentinel so
+   * that round-trips through JSON do not silently drop the field.
+   *
+   * @deprecated Prefer {@link parent} (structured). This field is preserved
+   *   for backward compatibility with V2 manifests written before PR 4/6.
+   */
+  parentCapsule: z.string().min(1).nullable(),
+  /**
+   * Structured fork-lineage pointer added in PR 4/6. When present, this
+   * capsule is a fork of the described parent. `null` is the explicit
+   * "not a fork" sentinel — round-trips through JSON cleanly without
+   * silently dropping the field.
+   *
+   * Defaults to `null` so that V2 manifests written before PR 4/6 (which
+   * omit this field) still parse without error. This preserves backward
+   * compatibility with the existing `makeV2Manifest()` test fixtures and
+   * any in-the-wild V2 archives produced by PR 2/6 and PR 3/6.
+   *
+   * Invariant: when `parent` is non-null, `parentCapsule` SHOULD equal
+   * `parent.capsuleId` for backward compatibility with readers that only
+   * understand the legacy field. `forkCapsule()` sets both.
+   */
+  parent: CapsuleParentSchema.nullable().default(null),
+  description: z.string(),
+  retrievalPolicy: CapsuleRetrievalPolicySchema,
+  includes: CapsuleIncludesSchema
+});
+var ExportManifestV2Schema = z.object({
+  format: z.literal("openclaw-engram-export"),
+  schemaVersion: z.literal(2),
+  createdAt: z.string(),
+  pluginVersion: z.string(),
+  includesTranscripts: z.boolean(),
+  files: z.array(
+    z.object({
+      path: z.string(),
+      sha256: z.string(),
+      bytes: z.number().int().nonnegative()
+    })
+  ),
+  capsule: CapsuleBlockSchema
+});
+var ExportBundleV2Schema = z.object({
+  manifest: ExportManifestV2Schema,
+  records: z.array(ExportMemoryRecordV1Schema)
+});
+function parseExportManifest(input) {
+  const version = typeof input === "object" && input !== null ? input.schemaVersion : void 0;
+  if (version === 2) {
+    const manifest = ExportManifestV2Schema.parse(input);
+    return {
+      capsuleVersion: 2,
+      manifest,
+      capsule: manifest.capsule
+    };
+  }
+  if (version === 1) {
+    const manifest = ExportManifestV1Schema.parse(input);
+    return { capsuleVersion: 1, manifest, capsule: null };
+  }
+  const v1 = ExportManifestV1Schema.safeParse(input);
+  if (v1.success) {
+    return { capsuleVersion: 1, manifest: v1.data, capsule: null };
+  }
+  const v2 = ExportManifestV2Schema.safeParse(input);
+  if (v2.success) {
+    return {
+      capsuleVersion: 2,
+      manifest: v2.data,
+      capsule: v2.data.capsule
+    };
+  }
+  throw v2.error;
+}
+function parseExportBundle(input) {
+  if (typeof input !== "object" || input === null) {
+    ExportBundleV1Schema.parse(input);
+    throw new Error("unreachable");
+  }
+  const manifestRaw = input.manifest;
+  const normalized = parseExportManifest(manifestRaw);
+  if (normalized.capsuleVersion === 2) {
+    const bundle2 = ExportBundleV2Schema.parse(input);
+    return { capsuleVersion: 2, bundle: bundle2, capsule: bundle2.manifest.capsule };
+  }
+  const bundle = ExportBundleV1Schema.parse(input);
+  return { capsuleVersion: 1, bundle, capsule: null };
+}
+
+export {
+  ExportManifestV1Schema,
+  ExportMemoryRecordV1Schema,
+  ExportBundleV1Schema,
+  CAPSULE_ID_PATTERN,
+  CapsuleRetrievalPolicySchema,
+  CapsuleIncludesSchema,
+  CapsuleParentSchema,
+  CapsuleBlockSchema,
+  ExportManifestV2Schema,
+  ExportBundleV2Schema,
+  parseExportManifest,
+  parseExportBundle
+};
+//# sourceMappingURL=chunk-OA3L7BFR.js.map

package/dist/chunk-OA3L7BFR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transfer/types.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport const ExportManifestV1Schema = z.object({\n  format: z.literal(\"openclaw-engram-export\"),\n  schemaVersion: z.literal(1),\n  createdAt: z.string(),\n  pluginVersion: z.string(),\n  includesTranscripts: z.boolean(),\n  files: z.array(\n    z.object({\n      path: z.string(),\n      sha256: z.string(),\n      bytes: z.number().int().nonnegative(),\n    }),\n  ),\n});\n\nexport type ExportManifestV1 = z.infer<typeof ExportManifestV1Schema>;\n\nexport const ExportMemoryRecordV1Schema = z.object({\n  path: z.string(),\n  content: z.string(),\n});\n\nexport type ExportMemoryRecordV1 = z.infer<typeof ExportMemoryRecordV1Schema>;\n\nexport const ExportBundleV1Schema = z.object({\n  manifest: ExportManifestV1Schema,\n  records: z.array(ExportMemoryRecordV1Schema),\n});\n\nexport type ExportBundleV1 = z.infer<typeof ExportBundleV1Schema>;\n\n// ---------------------------------------------------------------------------\n// V2 capsule manifest (issue #676 PR 1/6)\n// ---------------------------------------------------------------------------\n//\n// The V2 manifest extends V1 with a `capsule` block describing a reusable,\n// shareable bundle of memory state (\"capsule\"). This PR introduces ONLY the\n// schema and a backward-compatible reader. Actual export/import pipelines and\n// CLI surfaces are deferred to subsequent PRs (2/6 through 6/6).\n\n/**\n * Allowed pattern for a user-chosen capsule id.\n *\n * - lowercase or uppercase alphanumerics and dashes\n * - must start and end with an alphanumeric (no leading/trailing dashes)\n * - no consecutive dashes\n * - 1..64 characters\n *\n * The constraints are intentionally narrow so capsule ids round-trip cleanly\n * through filesystem paths, URLs, and registry slugs without escaping.\n */\nexport const CAPSULE_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?!-))*[A-Za-z0-9]$|^[A-Za-z0-9]$/;\n\nconst CapsuleIdSchema = z\n  .string()\n  .min(1, \"capsule.id must not be empty\")\n  .max(64, \"capsule.id must be 64 characters or fewer\")\n  .regex(\n    CAPSULE_ID_PATTERN,\n    \"capsule.id must be alphanumeric with single dashes (no spaces, no leading/trailing dashes)\",\n  );\n\n/**\n * Permissive semver-ish validator. We accept the common subset\n * `MAJOR.MINOR.PATCH` with optional pre-release / build suffixes. This is\n * intentionally looser than full semver 2.0 so capsule authors can use simple\n * versions like `1.0.0` or `0.1.0-rc.1` without pulling in a parser.\n */\nconst SemverLikeSchema = z\n  .string()\n  .min(1, \"capsule.version must not be empty\")\n  .regex(\n    /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/,\n    \"capsule.version must be a semver-like string (e.g. 1.0.0)\",\n  );\n\nexport const CapsuleRetrievalPolicySchema = z.object({\n  /**\n   * Per-tier weight overrides applied during recall when the capsule is the\n   * active scope. Keys are tier names (e.g. `bm25`, `vector`, `graph`); values\n   * are non-negative finite multipliers. The set of valid keys is left open\n   * for now so future tiers do not break older manifests.\n   */\n  tierWeights: z.record(\n    z.string().min(1),\n    z.number().finite().nonnegative(),\n  ),\n  /**\n   * Whether the direct-answer fast path is allowed when this capsule is\n   * active. Operators may disable it for capsules whose contents should\n   * always flow through the full retrieval pipeline.\n   */\n  directAnswerEnabled: z.boolean(),\n});\n\nexport type CapsuleRetrievalPolicy = z.infer<typeof CapsuleRetrievalPolicySchema>;\n\nexport const CapsuleIncludesSchema = z.object({\n  taxonomy: z.boolean(),\n  identityAnchors: z.boolean(),\n  peerProfiles: z.boolean(),\n  procedural: z.boolean(),\n});\n\nexport type CapsuleIncludes = z.infer<typeof CapsuleIncludesSchema>;\n\n/**\n * Structured linkage to the capsule that was forked to produce this one.\n *\n * - `capsuleId`  — the `id` field from the parent capsule's manifest block.\n * - `version`    — the `version` field from the parent capsule's manifest block\n *                  at the time the fork was taken.\n * - `forkRoot`   — the posix-relative directory prefix under which the parent's\n *                  records were planted inside the fork's memory root, e.g.\n *                  `forks/parent-id`. Stored here so downstream tooling can\n *                  locate the imported parent tree without re-parsing paths.\n */\nexport const CapsuleParentSchema = z.object({\n  capsuleId: CapsuleIdSchema,\n  version: SemverLikeSchema,\n  /**\n   * Posix-relative path prefix under the fork's memory root where the parent\n   * capsule's records were placed. Typically `forks/<parent-capsule-id>`.\n   * Must be a non-empty string with no leading slash.\n   */\n  forkRoot: z\n    .string()\n    .min(1, \"capsule.parent.forkRoot must not be empty\")\n    .refine((v) => !v.startsWith(\"/\"), {\n      message: \"capsule.parent.forkRoot must be a relative path (no leading slash)\",\n    }),\n});\n\nexport type CapsuleParent = z.infer<typeof CapsuleParentSchema>;\n\nexport const CapsuleBlockSchema = z.object({\n  id: CapsuleIdSchema,\n  version: SemverLikeSchema,\n  /**\n   * Taxonomy schema version the capsule was authored against. Free-form for\n   * now; later PRs may tighten this to a known taxonomy registry.\n   */\n  schemaVersion: z.string().min(1, \"capsule.schemaVersion must not be empty\"),\n  /**\n   * Optional reference to the parent capsule this one was forked or derived\n   * from. `null` (not `undefined`) is the explicit \"no parent\" sentinel so\n   * that round-trips through JSON do not silently drop the field.\n   *\n   * @deprecated Prefer {@link parent} (structured). This field is preserved\n   *   for backward compatibility with V2 manifests written before PR 4/6.\n   */\n  parentCapsule: z.string().min(1).nullable(),\n  /**\n   * Structured fork-lineage pointer added in PR 4/6. When present, this\n   * capsule is a fork of the described parent. `null` is the explicit\n   * \"not a fork\" sentinel — round-trips through JSON cleanly without\n   * silently dropping the field.\n   *\n   * Defaults to `null` so that V2 manifests written before PR 4/6 (which\n   * omit this field) still parse without error. This preserves backward\n   * compatibility with the existing `makeV2Manifest()` test fixtures and\n   * any in-the-wild V2 archives produced by PR 2/6 and PR 3/6.\n   *\n   * Invariant: when `parent` is non-null, `parentCapsule` SHOULD equal\n   * `parent.capsuleId` for backward compatibility with readers that only\n   * understand the legacy field. `forkCapsule()` sets both.\n   */\n  parent: CapsuleParentSchema.nullable().default(null),\n  description: z.string(),\n  retrievalPolicy: CapsuleRetrievalPolicySchema,\n  includes: CapsuleIncludesSchema,\n});\n\nexport type CapsuleBlock = z.infer<typeof CapsuleBlockSchema>;\n\nexport const ExportManifestV2Schema = z.object({\n  format: z.literal(\"openclaw-engram-export\"),\n  schemaVersion: z.literal(2),\n  createdAt: z.string(),\n  pluginVersion: z.string(),\n  includesTranscripts: z.boolean(),\n  files: z.array(\n    z.object({\n      path: z.string(),\n      sha256: z.string(),\n      bytes: z.number().int().nonnegative(),\n    }),\n  ),\n  capsule: CapsuleBlockSchema,\n});\n\nexport type ExportManifestV2 = z.infer<typeof ExportManifestV2Schema>;\n\nexport const ExportBundleV2Schema = z.object({\n  manifest: ExportManifestV2Schema,\n  records: z.array(ExportMemoryRecordV1Schema),\n});\n\nexport type ExportBundleV2 = z.infer<typeof ExportBundleV2Schema>;\n\n// ---------------------------------------------------------------------------\n// Backward-compatible reader\n// ---------------------------------------------------------------------------\n\nexport type AnyExportManifest = ExportManifestV1 | ExportManifestV2;\nexport type AnyExportBundle = ExportBundleV1 | ExportBundleV2;\n\n/**\n * Normalized form returned by {@link parseExportManifest}. Callers that don't\n * care about the wire-format version can branch on `capsuleVersion` (1 or 2)\n * and trust that V1 manifests surface as `{ capsuleVersion: 1, capsule: null }`.\n */\nexport interface NormalizedExportManifest {\n  capsuleVersion: 1 | 2;\n  manifest: AnyExportManifest;\n  capsule: CapsuleBlock | null;\n}\n\n/**\n * Parse an unknown manifest payload as either V1 or V2.\n *\n * Dispatch is driven by `schemaVersion` so we surface the most relevant\n * validation error per branch. If `schemaVersion` is missing or unknown we\n * fall back to V1 first (the historical wire format) and only report the V2\n * error if both branches fail.\n */\nexport function parseExportManifest(input: unknown): NormalizedExportManifest {\n  const version =\n    typeof input === \"object\" && input !== null\n      ? (input as { schemaVersion?: unknown }).schemaVersion\n      : undefined;\n\n  if (version === 2) {\n    const manifest = ExportManifestV2Schema.parse(input);\n    return {\n      capsuleVersion: 2,\n      manifest,\n      capsule: manifest.capsule,\n    };\n  }\n\n  if (version === 1) {\n    const manifest = ExportManifestV1Schema.parse(input);\n    return { capsuleVersion: 1, manifest, capsule: null };\n  }\n\n  // Unknown / missing schemaVersion: try V1 then V2 so the reader stays\n  // forgiving for hand-authored payloads but still produces a clear error.\n  const v1 = ExportManifestV1Schema.safeParse(input);\n  if (v1.success) {\n    return { capsuleVersion: 1, manifest: v1.data, capsule: null };\n  }\n  const v2 = ExportManifestV2Schema.safeParse(input);\n  if (v2.success) {\n    return {\n      capsuleVersion: 2,\n      manifest: v2.data,\n      capsule: v2.data.capsule,\n    };\n  }\n  // Surface the V2 error since callers introducing capsules likely care most\n  // about that branch's diagnostics.\n  throw v2.error;\n}\n\n/**\n * Convenience: parse a full bundle (manifest + records) accepting either V1\n * or V2 manifests. Records currently share the V1 shape across both versions.\n */\nexport function parseExportBundle(input: unknown): {\n  capsuleVersion: 1 | 2;\n  bundle: AnyExportBundle;\n  capsule: CapsuleBlock | null;\n} {\n  if (typeof input !== \"object\" || input === null) {\n    // Defer to V1 schema so the user sees a familiar zod error.\n    ExportBundleV1Schema.parse(input);\n    throw new Error(\"unreachable\");\n  }\n  const manifestRaw = (input as { manifest?: unknown }).manifest;\n  const normalized = parseExportManifest(manifestRaw);\n  if (normalized.capsuleVersion === 2) {\n    const bundle = ExportBundleV2Schema.parse(input);\n    return { capsuleVersion: 2, bundle, capsule: bundle.manifest.capsule };\n  }\n  const bundle = ExportBundleV1Schema.parse(input);\n  return { capsuleVersion: 1, bundle, capsule: null };\n}\n"],"mappings":"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","names":["bundle"]}

package/dist/chunk-OZHRDTDX.js

@@ -0,0 +1,240 @@
+// src/connectors-cli.ts
+var CONNECTORS_OUTPUT_FORMATS = ["text", "markdown", "json"];
+function parseConnectorsFormat(value, defaultFormat = "text") {
+  if (value === void 0 || value === null) return defaultFormat;
+  if (typeof value !== "string" || !CONNECTORS_OUTPUT_FORMATS.includes(value)) {
+    throw new Error(
+      `--format expects one of ${CONNECTORS_OUTPUT_FORMATS.join(", ")}; got ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
+function parseConnectorsListOptions(options) {
+  return {
+    format: parseConnectorsFormat(options.format, "text")
+  };
+}
+function parseConnectorsStatusOptions(options) {
+  return {
+    format: parseConnectorsFormat(options.format, "json")
+  };
+}
+function parseConnectorsRunName(rawName) {
+  if (typeof rawName !== "string" || rawName.trim().length === 0) {
+    throw new Error(
+      "connectors run: <name> is required and must be a non-empty connector id"
+    );
+  }
+  return rawName.trim();
+}
+function statusLabel(status) {
+  switch (status) {
+    case "never":
+      return "never synced";
+    case "success":
+      return "ok";
+    case "error":
+      return "error";
+    default:
+      return status;
+  }
+}
+function fmtTimestamp(value, fallback = "\u2014") {
+  if (!value) return fallback;
+  return value;
+}
+function renderConnectorsList(rows, format) {
+  if (format === "json") {
+    const out = rows.map((row) => ({
+      id: row.id,
+      displayName: row.displayName,
+      enabled: row.enabled,
+      lastSyncAt: row.state?.lastSyncAt ?? null,
+      lastSyncStatus: row.state?.lastSyncStatus ?? "never",
+      lastSyncError: row.state?.lastSyncError ?? null,
+      totalDocsImported: row.state?.totalDocsImported ?? 0,
+      updatedAt: row.state?.updatedAt ?? null
+    }));
+    return JSON.stringify(out, null, 2);
+  }
+  if (rows.length === 0) {
+    if (format === "markdown") {
+      return "# Live connectors\n\n_No live connectors are configured._\n";
+    }
+    return "No live connectors configured.";
+  }
+  if (format === "markdown") {
+    const lines2 = ["# Live connectors", ""];
+    lines2.push("| ID | Display name | Enabled | Last poll | Docs imported | Status |");
+    lines2.push("| --- | --- | --- | --- | --- | --- |");
+    for (const row of rows) {
+      const lastPoll = fmtTimestamp(row.state?.lastSyncAt);
+      const docs = row.state?.totalDocsImported ?? 0;
+      const status = statusLabel(row.state?.lastSyncStatus ?? "never");
+      lines2.push(
+        `| \`${row.id}\` | ${row.displayName} | ${row.enabled ? "yes" : "no"} | ${lastPoll} | ${docs} | ${status} |`
+      );
+      if (row.state?.lastSyncError) {
+        lines2.push(
+          `| | | | | | _Error: ${escapePipes(row.state.lastSyncError)}_ |`
+        );
+      }
+    }
+    return lines2.join("\n") + "\n";
+  }
+  const lines = [`Live connectors (${rows.length}):`];
+  lines.push("");
+  for (const row of rows) {
+    const enabledStr = row.enabled ? "enabled" : "disabled";
+    const status = statusLabel(row.state?.lastSyncStatus ?? "never");
+    const lastPoll = fmtTimestamp(row.state?.lastSyncAt, "(never polled)");
+    const docs = row.state?.totalDocsImported ?? 0;
+    lines.push(`  ${row.id}  (${row.displayName})`);
+    lines.push(`    state:         ${enabledStr}, ${status}`);
+    lines.push(`    last_poll:     ${lastPoll}`);
+    lines.push(`    docs_imported: ${docs}`);
+    if (row.state?.lastSyncError) {
+      lines.push(`    last_error:    ${row.state.lastSyncError}`);
+    }
+  }
+  return lines.join("\n");
+}
+function renderConnectorsRunResult(connectorId, result, format) {
+  const ok = result.error === void 0 && result.stateWriteError === void 0;
+  if (format === "json") {
+    return JSON.stringify(
+      {
+        connector: connectorId,
+        docsImported: result.docsImported,
+        error: result.error ?? null,
+        stateWriteError: result.stateWriteError ?? null,
+        ok
+      },
+      null,
+      2
+    );
+  }
+  if (format === "markdown") {
+    const lines2 = [`# connectors run: \`${connectorId}\``, ""];
+    lines2.push(`- **Status:** ${ok ? "success" : "error"}`);
+    lines2.push(`- **Docs imported:** ${result.docsImported}`);
+    if (result.error !== void 0) {
+      lines2.push(`- **Error:** ${result.error}`);
+    }
+    if (result.stateWriteError !== void 0) {
+      const label = result.error === void 0 ? "State-write error (cursor not advanced)" : "State-write error (error state not persisted)";
+      lines2.push(`- **${label}:** ${result.stateWriteError}`);
+    }
+    return lines2.join("\n") + "\n";
+  }
+  const lines = [];
+  if (ok) {
+    lines.push(`connectors run: ${connectorId} \u2014 OK`);
+    lines.push(`  docs_imported: ${result.docsImported}`);
+  } else {
+    lines.push(`connectors run: ${connectorId} \u2014 FAILED`);
+    lines.push(`  docs_imported: ${result.docsImported}`);
+    if (result.error !== void 0) {
+      lines.push(`  error:         ${result.error}`);
+    }
+    if (result.stateWriteError !== void 0) {
+      lines.push(
+        `  state_write_error: ${result.stateWriteError}`
+      );
+      if (result.error === void 0) {
+        lines.push(
+          result.docsImported > 0 ? `  (docs were ingested; cursor was not advanced \u2014 next poll will re-fetch from prior position)` : `  (cursor was not advanced \u2014 next poll will retry from prior position)`
+        );
+      } else {
+        lines.push(
+          `  (error state was not persisted \u2014 next poll will retry from prior position)`
+        );
+      }
+    }
+  }
+  return lines.join("\n");
+}
+async function runConnectorPollOnce(args) {
+  const { connectorId, priorState, syncFn, ingestFn, writeCursorFn } = args;
+  let syncResult;
+  let ingestError;
+  try {
+    syncResult = await syncFn(priorState?.cursor ?? null);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    let stateWriteError;
+    try {
+      await writeCursorFn({
+        cursor: priorState?.cursor ?? null,
+        lastSyncStatus: "error",
+        lastSyncError: msg,
+        totalDocsImported: priorState?.totalDocsImported ?? 0
+      });
+    } catch (writeErr) {
+      stateWriteError = writeErr instanceof Error ? writeErr.message : String(writeErr);
+      console.error(
+        `[remnic] connectors/${connectorId}: failed to persist error state after syncFn failure (${stateWriteError}); original error: ${msg}`
+      );
+    }
+    return {
+      docsImported: 0,
+      error: msg,
+      ...stateWriteError !== void 0 ? { stateWriteError } : {}
+    };
+  }
+  if (syncResult.newDocs.length > 0) {
+    try {
+      await ingestFn(syncResult.newDocs);
+    } catch (err) {
+      ingestError = err instanceof Error ? err.message : String(err);
+    }
+  }
+  if (ingestError !== void 0) {
+    let stateWriteError;
+    try {
+      await writeCursorFn({
+        cursor: priorState?.cursor ?? null,
+        lastSyncStatus: "error",
+        lastSyncError: ingestError,
+        totalDocsImported: priorState?.totalDocsImported ?? 0
+      });
+    } catch (writeErr) {
+      stateWriteError = writeErr instanceof Error ? writeErr.message : String(writeErr);
+      console.error(
+        `[remnic] connectors/${connectorId}: failed to persist error state after ingestFn failure (${stateWriteError}); original error: ${ingestError}`
+      );
+    }
+    return {
+      docsImported: 0,
+      error: ingestError,
+      ...stateWriteError !== void 0 ? { stateWriteError } : {}
+    };
+  }
+  const docsImported = syncResult.newDocs.length;
+  try {
+    await writeCursorFn({
+      cursor: syncResult.nextCursor,
+      lastSyncStatus: "success",
+      totalDocsImported: (priorState?.totalDocsImported ?? 0) + docsImported
+    });
+  } catch (writeErr) {
+    const writeMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+    return { docsImported, stateWriteError: writeMsg };
+  }
+  return { docsImported };
+}
+function escapePipes(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+
+export {
+  CONNECTORS_OUTPUT_FORMATS,
+  parseConnectorsFormat,
+  parseConnectorsListOptions,
+  parseConnectorsStatusOptions,
+  parseConnectorsRunName,
+  renderConnectorsList,
+  renderConnectorsRunResult,
+  runConnectorPollOnce
+};
+//# sourceMappingURL=chunk-OZHRDTDX.js.map

package/dist/chunk-OZHRDTDX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors-cli.ts"],"sourcesContent":["/**\n * `remnic connectors` CLI helpers (issue #683 PR 6/N).\n *\n * Three subcommands:\n *\n *   remnic connectors list\n *     Lists all configured live connectors, their enabled state, last poll\n *     time, and last error.  Output formats: text (default), markdown, json.\n *\n *   remnic connectors status\n *     Identical data to `list` but defaults to JSON output so scripts can\n *     reliably parse it.  Accepts `--format` to override.\n *\n *   remnic connectors run <name>\n *     Manually triggers a single `syncIncremental()` pass for the named\n *     connector.  Operator debug surface — useful when you want to test\n *     credentials without waiting for the scheduler tick.  Prints the\n *     number of new documents imported plus any error.\n *\n * Design decisions:\n *\n *   - Pure functions for list / status / run option parsing so they can be\n *     unit-tested without booting an orchestrator (CLAUDE.md rules 14 + 51).\n *   - Rendering lives here (not in cli.ts) so HTTP/MCP surfaces can reuse the\n *     same output without forking formatting (CLAUDE.md rule 22).\n *   - The `run` command requires the caller to pass a `pollFn` callback\n *     (wrapping the actual connector's `syncIncremental`).  This keeps the\n *     helper module free of direct orchestrator / live-connector imports while\n *     still being testable (CLAUDE.md rule 33 — mock signatures must match\n *     production).\n *   - CLAUDE.md rule 51: invalid `--format` throws with listed options; unknown\n *     connector name in `run` throws a descriptive error; `--format` without a\n *     value is caught by Commander's built-in argument check.\n *   - `runConnectorPollOnce` encapsulates the persist-before-cursor-advance\n *     contract (CLAUDE.md gotcha #25, #43) so it can be unit-tested in\n *     isolation without an orchestrator.\n */\n\nimport {\n  type ConnectorCursor,\n  type ConnectorDocument,\n  type ConnectorState,\n  type ConnectorSyncStatus,\n} from \"./connectors/live/index.js\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Types that cross the module boundary\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * A lightweight descriptor for one live connector, assembled from the parsed\n * config and any persisted state.  The CLI handler builds this from\n * `orchestrator.config.connectors` + `listConnectorStates(memoryDir)`.\n */\nexport interface ConnectorRow {\n  /** Stable connector id (e.g. `\"google-drive\"`, `\"notion\"`). */\n  id: string;\n  /** Human-readable display name. */\n  displayName: string;\n  /** Whether the operator has enabled this connector in config. */\n  enabled: boolean;\n  /** Persisted sync state, or `null` if no sync has ever run. */\n  state: ConnectorState | null;\n}\n\n/**\n * Result returned by the `run` command's poll function.\n */\nexport interface ConnectorRunResult {\n  /** Number of new documents imported in this pass. */\n  docsImported: number;\n  /**\n   * Error message if the sync or ingest failed, undefined on full success.\n   * When only the cursor write failed after a successful ingest, this field is\n   * undefined and `stateWriteError` carries the failure. When persisting error\n   * state fails after a sync/ingest error, both fields are set so callers can\n   * preserve the primary failure while also reporting stale persisted state.\n   */\n  error?: string;\n  /**\n   * Set when cursor/error-state persistence fails. On the success path,\n   * `docsImported` reflects the actual count of successfully ingested docs so\n   * the operator knows data was persisted even though the cursor did not\n   * advance. On the error path, `error` preserves the primary sync/ingest\n   * failure and this field reports the secondary persistence failure.\n   */\n  stateWriteError?: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Output formats\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport const CONNECTORS_OUTPUT_FORMATS = [\"text\", \"markdown\", \"json\"] as const;\nexport type ConnectorsOutputFormat = (typeof CONNECTORS_OUTPUT_FORMATS)[number];\n\n/**\n * Validate `--format <fmt>`.  Throws a listed-options error for any value not\n * in `CONNECTORS_OUTPUT_FORMATS`.  Returns the given default when the value is\n * `undefined` (no flag supplied).\n */\nexport function parseConnectorsFormat(\n  value: unknown,\n  defaultFormat: ConnectorsOutputFormat = \"text\",\n): ConnectorsOutputFormat {\n  if (value === undefined || value === null) return defaultFormat;\n  if (\n    typeof value !== \"string\" ||\n    !(CONNECTORS_OUTPUT_FORMATS as readonly string[]).includes(value)\n  ) {\n    throw new Error(\n      `--format expects one of ${CONNECTORS_OUTPUT_FORMATS.join(\", \")}; got ${JSON.stringify(value)}`,\n    );\n  }\n  return value as ConnectorsOutputFormat;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Parsed option types\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ParsedConnectorsListOptions {\n  format: ConnectorsOutputFormat;\n}\n\nexport interface ParsedConnectorsStatusOptions {\n  /** `status` defaults to JSON for scripting; `--format` can override. */\n  format: ConnectorsOutputFormat;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Option parsers (pure, unit-testable)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Validate the option bag for `remnic connectors list`.\n */\nexport function parseConnectorsListOptions(\n  options: Record<string, unknown>,\n): ParsedConnectorsListOptions {\n  return {\n    format: parseConnectorsFormat(options.format, \"text\"),\n  };\n}\n\n/**\n * Validate the option bag for `remnic connectors status`.\n * Defaults to `json` (machine-readable) unless `--format` overrides.\n */\nexport function parseConnectorsStatusOptions(\n  options: Record<string, unknown>,\n): ParsedConnectorsStatusOptions {\n  return {\n    format: parseConnectorsFormat(options.format, \"json\"),\n  };\n}\n\n/**\n * Validate the positional `<name>` argument for `remnic connectors run`.\n */\nexport function parseConnectorsRunName(rawName: unknown): string {\n  if (typeof rawName !== \"string\" || rawName.trim().length === 0) {\n    throw new Error(\n      \"connectors run: <name> is required and must be a non-empty connector id\",\n    );\n  }\n  return rawName.trim();\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Formatters: shared helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Human-readable summary of `ConnectorSyncStatus`.\n *\n * Does NOT fold in the enabled/disabled state — the text and markdown\n * renderers already display that separately.  Mixing them produced\n * \"state: disabled, disabled\" when `enabled=false` and `status=\"never\"`.\n */\nfunction statusLabel(status: ConnectorSyncStatus): string {\n  switch (status) {\n    case \"never\":\n      return \"never synced\";\n    case \"success\":\n      return \"ok\";\n    case \"error\":\n      return \"error\";\n    default:\n      return status;\n  }\n}\n\n/**\n * Format a UTC ISO timestamp for display.  If the value is `null` / `undefined`\n * returns the given fallback string.\n */\nfunction fmtTimestamp(value: string | null | undefined, fallback = \"—\"): string {\n  if (!value) return fallback;\n  return value;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Renderers\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Render connector rows for `remnic connectors list` / `remnic connectors status`.\n */\nexport function renderConnectorsList(\n  rows: readonly ConnectorRow[],\n  format: ConnectorsOutputFormat,\n): string {\n  if (format === \"json\") {\n    const out = rows.map((row) => ({\n      id: row.id,\n      displayName: row.displayName,\n      enabled: row.enabled,\n      lastSyncAt: row.state?.lastSyncAt ?? null,\n      lastSyncStatus: row.state?.lastSyncStatus ?? \"never\",\n      lastSyncError: row.state?.lastSyncError ?? null,\n      totalDocsImported: row.state?.totalDocsImported ?? 0,\n      updatedAt: row.state?.updatedAt ?? null,\n    }));\n    return JSON.stringify(out, null, 2);\n  }\n\n  if (rows.length === 0) {\n    if (format === \"markdown\") {\n      return \"# Live connectors\\n\\n_No live connectors are configured._\\n\";\n    }\n    return \"No live connectors configured.\";\n  }\n\n  if (format === \"markdown\") {\n    const lines: string[] = [\"# Live connectors\", \"\"];\n    lines.push(\"| ID | Display name | Enabled | Last poll | Docs imported | Status |\");\n    lines.push(\"| --- | --- | --- | --- | --- | --- |\");\n    for (const row of rows) {\n      const lastPoll = fmtTimestamp(row.state?.lastSyncAt);\n      const docs = row.state?.totalDocsImported ?? 0;\n      const status = statusLabel(row.state?.lastSyncStatus ?? \"never\");\n      lines.push(\n        `| \\`${row.id}\\` | ${row.displayName} | ${row.enabled ? \"yes\" : \"no\"} | ${lastPoll} | ${docs} | ${status} |`,\n      );\n      if (row.state?.lastSyncError) {\n        lines.push(\n          `| | | | | | _Error: ${escapePipes(row.state.lastSyncError)}_ |`,\n        );\n      }\n    }\n    return lines.join(\"\\n\") + \"\\n\";\n  }\n\n  // text\n  const lines: string[] = [`Live connectors (${rows.length}):`];\n  lines.push(\"\");\n  for (const row of rows) {\n    const enabledStr = row.enabled ? \"enabled\" : \"disabled\";\n    const status = statusLabel(row.state?.lastSyncStatus ?? \"never\");\n    const lastPoll = fmtTimestamp(row.state?.lastSyncAt, \"(never polled)\");\n    const docs = row.state?.totalDocsImported ?? 0;\n    lines.push(`  ${row.id}  (${row.displayName})`);\n    lines.push(`    state:         ${enabledStr}, ${status}`);\n    lines.push(`    last_poll:     ${lastPoll}`);\n    lines.push(`    docs_imported: ${docs}`);\n    if (row.state?.lastSyncError) {\n      lines.push(`    last_error:    ${row.state.lastSyncError}`);\n    }\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Render the result of a manual `remnic connectors run <name>` invocation.\n */\nexport function renderConnectorsRunResult(\n  connectorId: string,\n  result: ConnectorRunResult,\n  format: ConnectorsOutputFormat,\n): string {\n  // A run is \"ok\" when neither a sync/ingest error nor a state-write error\n  // is present.  A partial success (ingest ok, cursor write failed) still\n  // surfaces as a non-ok status so the operator knows to investigate.\n  const ok = result.error === undefined && result.stateWriteError === undefined;\n\n  if (format === \"json\") {\n    return JSON.stringify(\n      {\n        connector: connectorId,\n        docsImported: result.docsImported,\n        error: result.error ?? null,\n        stateWriteError: result.stateWriteError ?? null,\n        ok,\n      },\n      null,\n      2,\n    );\n  }\n\n  if (format === \"markdown\") {\n    const lines: string[] = [`# connectors run: \\`${connectorId}\\``, \"\"];\n    lines.push(`- **Status:** ${ok ? \"success\" : \"error\"}`);\n    lines.push(`- **Docs imported:** ${result.docsImported}`);\n    if (result.error !== undefined) {\n      lines.push(`- **Error:** ${result.error}`);\n    }\n    if (result.stateWriteError !== undefined) {\n      const label =\n        result.error === undefined\n          ? \"State-write error (cursor not advanced)\"\n          : \"State-write error (error state not persisted)\";\n      lines.push(`- **${label}:** ${result.stateWriteError}`);\n    }\n    return lines.join(\"\\n\") + \"\\n\";\n  }\n\n  // text\n  const lines: string[] = [];\n  if (ok) {\n    lines.push(`connectors run: ${connectorId} — OK`);\n    lines.push(`  docs_imported: ${result.docsImported}`);\n  } else {\n    lines.push(`connectors run: ${connectorId} — FAILED`);\n    lines.push(`  docs_imported: ${result.docsImported}`);\n    if (result.error !== undefined) {\n      lines.push(`  error:         ${result.error}`);\n    }\n    if (result.stateWriteError !== undefined) {\n      lines.push(\n        `  state_write_error: ${result.stateWriteError}`,\n      );\n      if (result.error === undefined) {\n        lines.push(\n          result.docsImported > 0\n            ? `  (docs were ingested; cursor was not advanced — next poll will re-fetch from prior position)`\n            : `  (cursor was not advanced — next poll will retry from prior position)`,\n        );\n      } else {\n        lines.push(\n          `  (error state was not persisted — next poll will retry from prior position)`,\n        );\n      }\n    }\n  }\n  return lines.join(\"\\n\");\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Poll orchestration helper\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Arguments for a single connector poll pass.\n *\n * All I/O is injectable so callers (cli.ts) can supply real implementations\n * and tests can supply lightweight stubs without booting an orchestrator.\n */\nexport interface RunConnectorPollOnceArgs {\n  /** Connector identifier (used in error/success state writes). */\n  connectorId: string;\n  /** Prior persisted state, or `null` on the very first sync. */\n  priorState: ConnectorState | null;\n  /**\n   * Perform a single incremental sync.  Returns newly-fetched documents and\n   * the cursor that should be persisted on success.\n   */\n  syncFn: (\n    cursor: ConnectorCursor | null,\n  ) => Promise<{ newDocs: ConnectorDocument[]; nextCursor: ConnectorCursor }>;\n  /**\n   * Ingest fetched documents into the memory layer.  Called BEFORE the cursor\n   * is advanced.  If this throws the cursor is NOT advanced (CLAUDE.md gotcha\n   * #25 — don't destroy old state before confirming new state succeeds).\n   */\n  ingestFn: (docs: ConnectorDocument[]) => Promise<void>;\n  /**\n   * Persist connector state (cursor + metadata).  Called after `ingestFn`\n   * succeeds (success path) or when `syncFn` / `ingestFn` throws (error path,\n   * with old cursor retained).\n   */\n  writeCursorFn: (state: {\n    cursor: ConnectorCursor | null;\n    lastSyncStatus: ConnectorSyncStatus;\n    lastSyncError?: string;\n    totalDocsImported: number;\n  }) => Promise<void>;\n}\n\n/**\n * Execute one `syncIncremental` pass for a live connector, enforcing the\n * persist-before-advance-cursor contract.\n *\n * Invariant (CLAUDE.md gotcha #25 + #43):\n *   1. `syncFn` fetches new docs and a next cursor.\n *   2. `ingestFn` persists the docs into the memory layer.\n *   3. Only if (2) succeeds does `writeCursorFn` advance the cursor.\n *   4. If (1) or (2) throws, `writeCursorFn` is still called but retains the\n *      **prior** cursor so the next poll re-fetches the same window.\n *\n * Returns the `ConnectorRunResult` that `cli.ts` uses for output rendering.\n */\nexport async function runConnectorPollOnce(\n  args: RunConnectorPollOnceArgs,\n): Promise<ConnectorRunResult> {\n  const { connectorId, priorState, syncFn, ingestFn, writeCursorFn } = args;\n\n  let syncResult: Awaited<ReturnType<typeof syncFn>> | undefined;\n  let ingestError: string | undefined;\n\n  // ── Phase 1: fetch ──────────────────────────────────────────────────────────\n  try {\n    syncResult = await syncFn(priorState?.cursor ?? null);\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    // syncFn failed — persist error state with the OLD cursor.\n    let stateWriteError: string | undefined;\n    try {\n      await writeCursorFn({\n        cursor: priorState?.cursor ?? null,\n        lastSyncStatus: \"error\",\n        lastSyncError: msg,\n        totalDocsImported: priorState?.totalDocsImported ?? 0,\n      });\n    } catch (writeErr) {\n      stateWriteError = writeErr instanceof Error ? writeErr.message : String(writeErr);\n      console.error(\n        `[remnic] connectors/${connectorId}: failed to persist error state after syncFn failure (${stateWriteError}); original error: ${msg}`,\n      );\n    }\n    return {\n      docsImported: 0,\n      error: msg,\n      ...(stateWriteError !== undefined ? { stateWriteError } : {}),\n    };\n  }\n\n  // ── Phase 2: ingest ─────────────────────────────────────────────────────────\n  // CRITICAL: ingest docs BEFORE advancing the cursor (CLAUDE.md gotcha #25).\n  // If ingestFn throws, write the error state with the OLD cursor so the\n  // next poll re-fetches the same document window.\n  if (syncResult.newDocs.length > 0) {\n    try {\n      await ingestFn(syncResult.newDocs);\n    } catch (err) {\n      ingestError = err instanceof Error ? err.message : String(err);\n    }\n  }\n\n  if (ingestError !== undefined) {\n    // ingestFn failed — persist error state with the OLD cursor.\n    let stateWriteError: string | undefined;\n    try {\n      await writeCursorFn({\n        cursor: priorState?.cursor ?? null,\n        lastSyncStatus: \"error\",\n        lastSyncError: ingestError,\n        totalDocsImported: priorState?.totalDocsImported ?? 0,\n      });\n    } catch (writeErr) {\n      stateWriteError = writeErr instanceof Error ? writeErr.message : String(writeErr);\n      // Intentionally not re-throwing: the original ingest error is the\n      // actionable failure for the operator.  The state-write failure is\n      // secondary and should not replace it in the rendered output.\n      // (CLAUDE.md gotcha #13; Codex P2 thread PRRT_kwDORJXyws59sk8K,\n      //  Cursor thread PRRT_kwDORJXyws59slAG)\n      console.error(\n        `[remnic] connectors/${connectorId}: failed to persist error state after ingestFn failure (${stateWriteError}); original error: ${ingestError}`,\n      );\n    }\n    return {\n      docsImported: 0,\n      error: ingestError,\n      ...(stateWriteError !== undefined ? { stateWriteError } : {}),\n    };\n  }\n\n  // ── Phase 3: advance cursor ─────────────────────────────────────────────────\n  // Ingest succeeded — advance the cursor.  If the cursor write fails, the\n  // docs ARE already in the memory layer so we must report the actual\n  // docsImported count.  Surface the state-write failure as a separate\n  // `stateWriteError` field so the operator can diagnose it without\n  // confusing it with a sync/ingest failure (Codex P1 thread\n  // PRRT_kwDORJXyws59sm76, Cursor thread PRRT_kwDORJXyws59sm_N).\n  const docsImported = syncResult.newDocs.length;\n  try {\n    await writeCursorFn({\n      cursor: syncResult.nextCursor,\n      lastSyncStatus: \"success\",\n      totalDocsImported: (priorState?.totalDocsImported ?? 0) + docsImported,\n    });\n  } catch (writeErr) {\n    const writeMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);\n    // Docs are already ingested — preserve the count so the operator knows\n    // data was persisted.  The next poll will re-fetch from the prior cursor\n    // position but that only causes duplicate-ingest, not data loss.\n    return { docsImported, stateWriteError: writeMsg };\n  }\n\n  return { docsImported };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Internal helpers\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Escape characters that would break a Markdown table cell (backslash first,\n * then pipe).  Same pattern as in `patterns-cli.ts`.\n */\nfunction escapePipes(value: string): string {\n  return value.replace(/\\\\/g, \"\\\\\\\\\").replace(/\\|/g, \"\\\\|\");\n}\n"],"mappings":"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","names":["lines"]}