@knowzai/cli 0.1.0 → 0.3.0

package/dist/lib/platform-release-manifest.js

@@ -65,6 +65,30 @@ export function parsePlatformReleaseManifest(value) {
     });
     return { releases };
 }
+/** Semver-newest manifest entry carrying the required flavor; undefined when none does. */
+export function newestManifestVersion(manifest, flavor) {
+    let newest;
+    for (const release of manifest.releases) {
+        if (!release.flavors.includes(flavor))
+            continue;
+        if (newest === undefined || compareVersions(release.version, newest) > 0)
+            newest = release.version;
+    }
+    return newest;
+}
+/**
+ * §2026-08-31 R4 runtime freshness notice. Pure — the caller supplies the manifest
+ * (already-fetched on the self-serve path, bounded advisory fetch elsewhere) and
+ * decides whether/where to log. Returns undefined when the booted version is
+ * already the newest known release of the flavor (never advises a downgrade).
+ * Copy frozen at the WG consistency review (`platform upgrade --version <semver>`).
+ */
+export function releaseFreshnessNotice(input) {
+    const newest = newestManifestVersion(input.manifest, input.flavor);
+    if (!newest || compareVersions(newest, input.currentVersion) <= 0)
+        return undefined;
+    return `Newer Knowz Platform ${newest} is available — run 'knowz platform upgrade --version ${newest}' after setup.`;
+}
 export function resolvePlatformRelease(input) {
     const releases = [...input.manifest.releases].sort((a, b) => compareVersions(b.version, a.version));
     if (input.requestedVersion) {

package/dist/lib/platform-release-manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-release-manifest.js","sourceRoot":"","sources":["../../src/lib/platform-release-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAsB,MAAM,eAAe,CAAC;AA6BzE,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAC/C,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,iCAAiC,MAAM,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IAC7C,IAAI,CAAqB;IAElC,YACE,OAAe,EACf,IAAwB,EACxB,WAA0B,QAAQ,CAAC,GAAG;QAEtC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,GAAG,4CAA4C,CAAC;AAEhE,SAAS,eAAe,CAAC,IAAY,EAAE,KAAa;IAClD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAChC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,eAAe;IACtB,MAAM,IAAI,wBAAwB,CAChC,+EAA+E,EAC/E,6BAA6B,CAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAE,KAAgC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9G,OAAO,eAAe,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,QAAQ,GAAI,KAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAmB,EAAE;QAC1F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,eAAe,EAAE,CAAC;QAC1E,MAAM,OAAO,GAAG,KAAgC,CAAC;QACjD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IACE,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;YACnC,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YACjC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YACvB,OAAO,CAAC,MAAM,KAAK,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,cAAc,CAAC;YAC5E,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACtC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC5C,CAAC,OAAO,CAAC,aAAa,KAAK,IAAI;gBAC7B,CAAC,OAAO,OAAO,CAAC,aAAa,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;YACzF,CAAC,OAAO,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC;YAC7D,CAAC,OAAO,CAAC,OAAO,KAAK,IAAI;gBACvB,CAAC,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;oBAClC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;oBAC9B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAC7E,CAAC;YACD,OAAO,eAAe,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,CAAC,GAAG,OAAO,CAA4B;YAChD,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,aAAa,EAAE,OAAO,CAAC,aAA8B;YACrD,KAAK,EAAE,OAAO,CAAC,KAAsB;YACrC,OAAO,EAAE,OAAO,CAAC,OAAwC;SAC1D,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAMtC;IACC,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACpG,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAC3B,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,OAAO,KAAK,KAAK,CAAC,gBAAgB;YAC5C,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,CACnD,CAAC;QACF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,wBAAwB,CAChC,WAAW,KAAK,CAAC,gBAAgB,8CAA8C,KAAK,CAAC,WAAW,0EAA0E,EAC1K,uBAAuB,EACvB,QAAQ,CAAC,KAAK,CACf,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,aAAa,IAAI,eAAe,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1F,MAAM,IAAI,wBAAwB,CAChC,kBAAkB,OAAO,CAAC,OAAO,uBAAuB,OAAO,CAAC,aAAa,uBAAuB,KAAK,CAAC,UAAU,uDAAuD,EAC3K,sBAAsB,EACtB,QAAQ,CAAC,KAAK,CACf,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IACtG,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CACnC,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,aAAa,KAAK,IAAI;QAChC,eAAe,CAAC,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAClE,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,wBAAwB,CAChC,6EAA6E,KAAK,CAAC,cAAc,kBAAkB,KAAK,CAAC,UAAU,GAAG,EACtI,uBAAuB,EACvB,QAAQ,CAAC,QAAQ,CAClB,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CACnC,CAAC,SAAS,EAAE,EAAE,CACZ,eAAe,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;QACvD,SAAS,CAAC,aAAa,KAAK,IAAI;QAChC,eAAe,CAAC,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CACjE,CAAC;IACF,OAAO;QACL,OAAO;QACP,GAAG,CAAC,OAAO,EAAE,aAAa;YACxB,CAAC,CAAC;gBACE,IAAI,EACF,wBAAwB,OAAO,CAAC,OAAO,wCAAwC,OAAO,CAAC,aAAa,YAAY;oBAChH,aAAa,KAAK,CAAC,UAAU,YAAY,OAAO,CAAC,OAAO,uCAAuC;aAClG;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"platform-release-manifest.js","sourceRoot":"","sources":["../../src/lib/platform-release-manifest.ts"],"names":[],"mappings":"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"}

package/dist/lib/portability-shared.d.ts

@@ -0,0 +1,49 @@
+import { KnowzError } from '@knowzai/core';
+import type { ExportScopeInput, ImportValidation, ImportOutcome } from '@knowzai/api-client';
+/**
+ * Pure decision + rendering helpers shared by `knowz export`, `knowz import`
+ * and `knowz transfer` (CLI_PortabilityTransfer, CLI_InstanceTransfer).
+ * Everything here is unit-testable without a network or a TTY.
+ */
+export declare const PORTABILITY_USER_KEY_GUIDANCE: string;
+/** Reject a tenant `kz_` key BEFORE any HTTP call, naming the profile and the fix. */
+export declare function assertPortabilityKeyKind(key: string | undefined, profile?: string): void;
+/**
+ * Fallback for credentials the CLI cannot classify locally: a portability 401
+ * means "authenticated but no user identity", not "not logged in" — replace the
+ * generic re-login hint with the actionable copy.
+ */
+export declare function mapPortabilityAuthError(e: unknown): KnowzError | undefined;
+export interface ScopeFlags {
+    scope?: string;
+    vaultId?: string;
+    itemIds?: string[];
+}
+export declare function inferExportScope(flags: ScopeFlags): ExportScopeInput;
+export declare function detectPackageKind(path: string): 'zip' | 'json';
+export declare function defaultExportFileName(mode: 'Light' | 'Full', at?: Date): string;
+/** `--out` may name a file OR an existing directory; omitted ⇒ default name in cwd. */
+export declare function resolveExportOutPath(out: string | undefined, mode: 'Light' | 'Full', at?: Date): string;
+/** Multi-part outputs land as `<out>.part{N}.zip` (R5); a trailing .zip on out collapses. */
+export declare function partOutPath(outPath: string, partNumber: number): string;
+/** Part-level resume (R5): skip only when the on-disk size equals `sizeBytes` exactly. */
+export declare function shouldSkipExistingPart(path: string, sizeBytes: number): boolean;
+export type ImportGateDecision = 'proceed' | 'prompt' | 'refuse';
+export declare function decideImportGate(input: {
+    confirmationRequired: boolean;
+    interactive: boolean;
+    yes: boolean;
+}): ImportGateDecision;
+export declare function totalConflicts(v: Pick<ImportValidation, 'conflictingVaults' | 'conflictingKnowledgeItems' | 'conflictingTopics' | 'conflictingPersons'>): number;
+/** Central `/import` has no explicit body-size limit — Kestrel's ~28 MB default applies (R10). */
+export declare const LARGE_JSON_WARN_BYTES: number;
+/** R10 — warn strictly ABOVE the threshold (25 MB exactly is still fine). */
+export declare function shouldWarnLargeJson(sizeBytes: number): boolean;
+export declare function isJobComplete(status: string): boolean;
+export declare function isJobFailed(status: string): boolean;
+export declare function renderValidationPreview(v: ImportValidation): string[];
+/** Per-category report (R9) — a partial import is never collapsed into a cheerful success. */
+export declare function renderImportOutcome(o: ImportOutcome): string[];
+/** A progress ticker on stderr — suppressed for non-TTY stderr and in --json mode (R4). */
+export declare function makeDownloadProgress(jsonMode: boolean): ((bytes: number, total?: number) => void) | undefined;
+//# sourceMappingURL=portability-shared.d.ts.map

package/dist/lib/portability-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portability-shared.d.ts","sourceRoot":"","sources":["../../src/lib/portability-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAY,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EAEd,MAAM,qBAAqB,CAAC;AAE7B;;;;GAIG;AAUH,eAAO,MAAM,6BAA6B,QAGP,CAAC;AAEpC,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAQxF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAU1E;AAID,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAgCpE;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAgB9D;AAYD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAE3F;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAQnH;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,0FAA0F;AAC1F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAO/E;AAID,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;CACd,GAAG,kBAAkB,CAGrB;AAED,wBAAgB,cAAc,CAC5B,CAAC,EAAE,IAAI,CACL,gBAAgB,EAChB,mBAAmB,GAAG,2BAA2B,GAAG,mBAAmB,GAAG,oBAAoB,CAC/F,GACA,MAAM,CAER;AAED,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAEtD,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE9D;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAID,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAuBrE;AAQD,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,EAAE,CAqB9D;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAU7G"}

package/dist/lib/portability-shared.js

@@ -0,0 +1,220 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { KnowzError, ExitCode } from '@knowzai/core';
+import { ApiError } from '@knowzai/types';
+/**
+ * Pure decision + rendering helpers shared by `knowz export`, `knowz import`
+ * and `knowz transfer` (CLI_PortabilityTransfer, CLI_InstanceTransfer).
+ * Everything here is unit-testable without a network or a TTY.
+ */
+// --- key-kind preflight + 401 mapping (smoke MED) -----------------------------
+//
+// The portability endpoints resolve a USER identity from the credential
+// (`ExtractUserId` in PortabilityEndpoints.cs) — a tenant `kz_` key
+// authenticates but carries none, so the server answers 401 even though the
+// profile IS logged in. Mirror of the peer-command `ukz_` preflight pattern:
+// detect locally where the key is readable; map the 401 for opaque credentials.
+export const PORTABILITY_USER_KEY_GUIDANCE = 'Export/import/transfer need a key that carries a user identity — a personal ukz_ key. ' +
+    'Mint one with `knowz login` (choose a personal key) or POST /api/v1/apikeys with keyType "user", ' +
+    'then store it for this profile.';
+/** Reject a tenant `kz_` key BEFORE any HTTP call, naming the profile and the fix. */
+export function assertPortabilityKeyKind(key, profile) {
+    if (key?.startsWith('kz_')) {
+        throw new KnowzError(`${profile ? `Profile '${profile}' holds` : 'The stored credential is'} a tenant API key (kz_), ` +
+            `which carries no user identity. ${PORTABILITY_USER_KEY_GUIDANCE}`, ExitCode.Auth);
+    }
+}
+/**
+ * Fallback for credentials the CLI cannot classify locally: a portability 401
+ * means "authenticated but no user identity", not "not logged in" — replace the
+ * generic re-login hint with the actionable copy.
+ */
+export function mapPortabilityAuthError(e) {
+    if (e instanceof ApiError && e.status === 401) {
+        return new KnowzError(`The server rejected this credential for portability (401): it authenticates but carries no ` +
+            `user identity. ${PORTABILITY_USER_KEY_GUIDANCE}`, ExitCode.Auth, { cause: e });
+    }
+    return undefined;
+}
+export function inferExportScope(flags) {
+    const items = flags.itemIds?.length ? flags.itemIds : undefined;
+    const vaultIds = flags.vaultId ? [flags.vaultId] : undefined;
+    switch (flags.scope) {
+        case 'tenant':
+            if (items || vaultIds) {
+                throw new KnowzError('--scope tenant exports everything — drop --vault/--items.', ExitCode.Usage);
+            }
+            return { scopeType: 'Tenant' };
+        case 'vault':
+        case 'vault-with-children':
+            if (!vaultIds)
+                throw new KnowzError(`--scope ${flags.scope} requires --vault.`, ExitCode.Usage);
+            return { scopeType: flags.scope === 'vault' ? 'Vault' : 'VaultWithChildren', vaultIds };
+        case 'items':
+            if (!items)
+                throw new KnowzError('--scope items requires --items.', ExitCode.Usage);
+            return { scopeType: items.length === 1 ? 'SingleItem' : 'MultiSelect', knowledgeItemIds: items };
+        case undefined:
+            break;
+        default:
+            throw new KnowzError(`Unknown --scope '${flags.scope}'.`, ExitCode.Usage);
+    }
+    if (items && vaultIds) {
+        throw new KnowzError('Give either --vault or --items (or an explicit --scope), not both.', ExitCode.Usage);
+    }
+    if (items)
+        return { scopeType: items.length === 1 ? 'SingleItem' : 'MultiSelect', knowledgeItemIds: items };
+    if (vaultIds)
+        return { scopeType: 'Vault', vaultIds };
+    return { scopeType: 'Tenant' };
+}
+// --- payload kind by magic bytes, never by extension (R8) ---------------------
+const ZIP_MAGIC = Buffer.from('PK\x03\x04', 'binary');
+export function detectPackageKind(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch (e) {
+        // L4 — a missing/unreadable package file is a usage problem, not a crash.
+        const code = e.code ?? (e instanceof Error ? e.message : String(e));
+        throw new KnowzError(`Cannot read package file '${path}' (${code}).`, ExitCode.Usage);
+    }
+    try {
+        const head = Buffer.alloc(4);
+        const read = readSync(fd, head, 0, 4, 0);
+        return read === 4 && head.equals(ZIP_MAGIC) ? 'zip' : 'json';
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// --- out-path handling (R4/R5) ------------------------------------------------
+function utcStamp(at) {
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    return (`${at.getUTCFullYear()}${p(at.getUTCMonth() + 1)}${p(at.getUTCDate())}` +
+        `-${p(at.getUTCHours())}${p(at.getUTCMinutes())}${p(at.getUTCSeconds())}`);
+}
+export function defaultExportFileName(mode, at = new Date()) {
+    return `knowz-export-${utcStamp(at)}.${mode === 'Full' ? 'zip' : 'json'}`;
+}
+/** `--out` may name a file OR an existing directory; omitted ⇒ default name in cwd. */
+export function resolveExportOutPath(out, mode, at = new Date()) {
+    if (!out)
+        return defaultExportFileName(mode, at);
+    try {
+        if (statSync(out).isDirectory())
+            return join(out, defaultExportFileName(mode, at));
+    }
+    catch {
+        // not an existing path — treat as a file name
+    }
+    return out;
+}
+/** Multi-part outputs land as `<out>.part{N}.zip` (R5); a trailing .zip on out collapses. */
+export function partOutPath(outPath, partNumber) {
+    return `${outPath.replace(/\.zip$/i, '')}.part${partNumber}.zip`;
+}
+/** Part-level resume (R5): skip only when the on-disk size equals `sizeBytes` exactly. */
+export function shouldSkipExistingPart(path, sizeBytes) {
+    if (!existsSync(path))
+        return false;
+    try {
+        return statSync(path).size === sizeBytes;
+    }
+    catch {
+        return false;
+    }
+}
+export function decideImportGate(input) {
+    if (!input.confirmationRequired || input.yes)
+        return 'proceed';
+    return input.interactive ? 'prompt' : 'refuse';
+}
+export function totalConflicts(v) {
+    return v.conflictingVaults + v.conflictingKnowledgeItems + v.conflictingTopics + v.conflictingPersons;
+}
+/** Central `/import` has no explicit body-size limit — Kestrel's ~28 MB default applies (R10). */
+export const LARGE_JSON_WARN_BYTES = 25 * 1024 * 1024;
+/** R10 — warn strictly ABOVE the threshold (25 MB exactly is still fine). */
+export function shouldWarnLargeJson(sizeBytes) {
+    return sizeBytes > LARGE_JSON_WARN_BYTES;
+}
+// --- export job status classification ----------------------------------------
+export function isJobComplete(status) {
+    const s = status.toLowerCase();
+    return s === 'complete' || s === 'completed';
+}
+export function isJobFailed(status) {
+    return ['failed', 'error', 'cancelled', 'canceled'].includes(status.toLowerCase());
+}
+// --- human rendering ----------------------------------------------------------
+export function renderValidationPreview(v) {
+    const lines = [];
+    lines.push(`Package: schema v${v.schemaVersion} (${v.schemaCompatible ? 'compatible' : 'INCOMPATIBLE'})` +
+        (v.sourceEdition ? ` — source: ${v.sourceEdition}` : ''));
+    if (v.schemaError)
+        lines.push(`Schema error: ${v.schemaError}`);
+    lines.push(`Contents: ${v.totalVaults} vault(s), ${v.totalKnowledgeItems} item(s), ${v.totalTopics} topic(s), ` +
+        `${v.totalTags} tag(s), ${v.totalPersons} person(s), ${v.totalLocations} location(s), ` +
+        `${v.totalEvents} event(s), ${v.totalComments} comment(s), ${v.totalFileRecords} file(s)`);
+    const conflicts = totalConflicts(v);
+    lines.push(conflicts > 0
+        ? `Conflicts: ${v.conflictingVaults} vault(s), ${v.conflictingKnowledgeItems} item(s), ` +
+            `${v.conflictingTopics} topic(s), ${v.conflictingPersons} person(s)`
+        : 'Conflicts: none');
+    for (const w of v.warnings)
+        lines.push(`Warning: ${w}`);
+    for (const e of v.errors)
+        lines.push(`Error: ${e}`);
+    lines.push(v.isValid ? 'Validation: PASSED' : 'Validation: FAILED');
+    return lines;
+}
+function countsLine(label, c) {
+    const total = c.created + c.skipped + c.overwritten + c.merged;
+    if (total === 0)
+        return undefined;
+    return `  ${label}: ${c.created} created, ${c.skipped} skipped, ${c.overwritten} overwritten, ${c.merged} merged`;
+}
+/** Per-category report (R9) — a partial import is never collapsed into a cheerful success. */
+export function renderImportOutcome(o) {
+    const lines = [o.success ? 'Import completed.' : `Import FAILED${o.error ? `: ${o.error}` : '.'}`];
+    const categories = [
+        ['vaults', o.vaults],
+        ['knowledge items', o.knowledgeItems],
+        ['topics', o.topics],
+        ['tags', o.tags],
+        ['persons', o.persons],
+        ['locations', o.locations],
+        ['events', o.events],
+        ['comments', o.comments],
+        ['file records', o.fileRecords],
+    ];
+    for (const [label, counts] of categories) {
+        const line = countsLine(label, counts);
+        if (line)
+            lines.push(line);
+    }
+    if (o.junctionsRestored > 0)
+        lines.push(`  junctions restored: ${o.junctionsRestored}`);
+    if (o.filesBlobFailed > 0)
+        lines.push(`  FILE BLOBS FAILED: ${o.filesBlobFailed}`);
+    for (const w of o.warnings)
+        lines.push(`Warning: ${w}`);
+    return lines;
+}
+/** A progress ticker on stderr — suppressed for non-TTY stderr and in --json mode (R4). */
+export function makeDownloadProgress(jsonMode) {
+    if (jsonMode || !process.stderr.isTTY)
+        return undefined;
+    let lastRender = 0;
+    return (bytes, total) => {
+        const now = Date.now();
+        if (now - lastRender < 200)
+            return;
+        lastRender = now;
+        const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+        process.stderr.write(`\r${mb(bytes)} MB${total ? ` / ${mb(total)} MB` : ''} `);
+    };
+}
+//# sourceMappingURL=portability-shared.js.map

package/dist/lib/portability-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portability-shared.js","sourceRoot":"","sources":["../../src/lib/portability-shared.ts"],"names":[],"mappings":"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"}

package/dist/lib/project-mcp-config.d.ts

@@ -0,0 +1,14 @@
+export interface ProjectMcpInstallResult {
+    path: string;
+    changed: boolean;
+    dryRun: boolean;
+    entry: {
+        command: string;
+        args: string[];
+    };
+}
+export declare function installProjectMcpConfig(repoRoot: string, opts?: {
+    dryRun?: boolean;
+    command?: string;
+}): ProjectMcpInstallResult;
+//# sourceMappingURL=project-mcp-config.d.ts.map

package/dist/lib/project-mcp-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-mcp-config.d.ts","sourceRoot":"","sources":["../../src/lib/project-mcp-config.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC5C;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,uBAAuB,CAqCzB"}

package/dist/lib/project-mcp-config.js

@@ -0,0 +1,78 @@
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { ExitCode, KnowzError } from '@knowzai/core';
+const MAX_PROJECT_MCP_CONFIG_BYTES = 1024 * 1024;
+const O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
+export function installProjectMcpConfig(repoRoot, opts = {}) {
+    const root = realpathSync(repoRoot);
+    const path = join(root, '.mcp.json');
+    const entry = {
+        command: opts.command ?? 'knowz',
+        args: ['mcp', 'serve', '--path', root],
+    };
+    const current = readExisting(path);
+    const servers = current.mcpServers;
+    if (servers !== undefined && (!servers || typeof servers !== 'object' || Array.isArray(servers))) {
+        throw new KnowzError(`Invalid mcpServers object in ${path}`, ExitCode.Usage);
+    }
+    const existingEntry = servers?.['knowz-local'];
+    const changed = JSON.stringify(existingEntry) !== JSON.stringify(entry);
+    const result = { path, changed, dryRun: Boolean(opts.dryRun), entry };
+    if (!changed || opts.dryRun)
+        return result;
+    const next = {
+        ...current,
+        mcpServers: {
+            ...(servers ?? {}),
+            'knowz-local': entry,
+        },
+    };
+    const temp = join(root, `.mcp.json.${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            unlinkSync(temp);
+    }
+    return result;
+}
+function readExisting(path) {
+    if (!existsSync(path))
+        return {};
+    if (lstatSync(path).isSymbolicLink()) {
+        throw new KnowzError(`Refusing symbolic link MCP config: ${path}`, ExitCode.Usage);
+    }
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDONLY | O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error('target is not a regular file');
+        if (stat.size > MAX_PROJECT_MCP_CONFIG_BYTES) {
+            throw new KnowzError(`MCP config exceeds the 1 MiB limit at ${path}`, ExitCode.Usage);
+        }
+        const parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('root is not an object');
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof KnowzError)
+            throw error;
+        throw new KnowzError(`Malformed MCP JSON at ${path}`, ExitCode.Usage, { cause: error });
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+//# sourceMappingURL=project-mcp-config.js.map

package/dist/lib/project-mcp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-mcp-config.js","sourceRoot":"","sources":["../../src/lib/project-mcp-config.ts"],"names":[],"mappings":"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"}

package/dist/lib/release-package-graph.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Release package-graph contract (CLI_SecurityReleaseReadiness H1 + H2).
+ *
+ * H1 — the release/CI workflows must address the CLI package by its CANONICAL
+ * published name, read from `packages/cli/package.json`. A stale `--filter`
+ * (e.g. the pre-rename `@knowz/cli`) makes every build/publish step a silent
+ * no-op: pnpm exits 0 having matched zero projects, so a release can "succeed"
+ * without ever building, packing, or publishing the CLI.
+ *
+ * H2 — `@knowzai/cli` depends on seven sibling workspace packages via
+ * `workspace:*`. Publishing only the CLI produces an UNINSTALLABLE package: the
+ * `workspace:*` specifiers are rewritten to the siblings' own (unstamped)
+ * versions, which were never published. The whole runtime graph must therefore
+ * be stamped to one version and published in dependency order, and a
+ * pack/install smoke must prove resolution with no `workspace:` leakage.
+ *
+ * This module is pure (filesystem reads only) so both the CI scripts and the
+ * unit tests drive exactly the same logic.
+ */
+/** Directory name, under `packages/`, of the package that ships the `knowz` bin. */
+export declare const CLI_PACKAGE_DIR = "cli";
+export interface PackageManifest {
+    name?: string;
+    version?: string;
+    private?: boolean;
+    bin?: unknown;
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+export interface WorkspacePackage {
+    /** Published package name, e.g. `@knowzai/cli`. */
+    name: string;
+    /** Directory name under `packages/`, e.g. `cli`. */
+    dir: string;
+    /** Absolute path to the package directory. */
+    path: string;
+    manifest: PackageManifest;
+}
+export interface WorkflowSource {
+    /** Repo-relative path, used only for failure messages. */
+    path: string;
+    source: string;
+}
+export interface WorkflowFilterUse {
+    /** 1-indexed line number within the workflow source. */
+    line: number;
+    /** The scoped package name the `--filter` addresses. */
+    filter: string;
+}
+/** Read every `packages/*` manifest that declares a name. */
+export declare function readWorkspacePackages(packagesDir: string): WorkspacePackage[];
+/**
+ * The one true CLI package name. Everything else (workflow filters, publish
+ * order, install smoke) is derived from this rather than hardcoded, so a future
+ * rename cannot leave a workflow silently addressing a package that no longer
+ * exists.
+ */
+export declare function canonicalCliPackageName(packagesDir: string): string;
+/** The npm scope shared by every internal package, derived from the CLI name. */
+export declare function canonicalScope(cliPackageName: string): string;
+/** Internal (workspace-resident) runtime dependencies declared by one manifest. */
+export declare function internalRuntimeDependencies(manifest: PackageManifest, internalNames: ReadonlySet<string>): string[];
+/**
+ * Dependency-ordered publish plan for the runtime graph reachable from `rootName`.
+ * Dependencies always precede their dependents, so each `npm publish` lands only
+ * after everything it declares is already resolvable on the registry.
+ */
+export declare function resolvePublishOrder(packages: readonly WorkspacePackage[], rootName: string): WorkspacePackage[];
+/**
+ * Every `pnpm --filter <@scope/name>` use in a workflow. Both `--filter x` and
+ * `--filter=x` spellings are recognised; unscoped filters (paths, globs) are
+ * ignored because only the scoped package identity is under contract here.
+ */
+export declare function findWorkflowPackageFilters(source: string): WorkflowFilterUse[];
+/**
+ * VERIFY H1 — fail when any workflow filter diverges from the canonical package
+ * identity. Returns human-readable failures (empty ⇒ pass) so both the CI script
+ * and the unit test can assert on the same values.
+ */
+export declare function assertCanonicalWorkflowFilters(workflows: readonly WorkflowSource[], knownPackageNames: ReadonlySet<string>): string[];
+/**
+ * VERIFY H1 (stronger half) — the workflows must actually address the canonical
+ * CLI package somewhere, so a filter that is simply deleted is caught too.
+ */
+export declare function assertCliPackageIsAddressed(workflows: readonly WorkflowSource[], cliPackageName: string): string[];
+/**
+ * VERIFY H2 — a manifest that is about to be packed/published must not leak a
+ * `workspace:` specifier, and every internal dependency must be pinned to the
+ * exact release version (they are published together, so a range would let a
+ * consumer resolve a sibling from a different release).
+ */
+export declare function assertPublishableManifest(manifest: PackageManifest, opts: {
+    version: string;
+    internalNames: ReadonlySet<string>;
+    label: string;
+}): string[];
+/** A semver prerelease is anything with a `-` pre-release segment (`1.2.3-rc.1`). */
+export declare function isPrereleaseVersion(version: string): boolean;
+/**
+ * Decide the npm dist-tag for a publish run, and REFUSE rather than guess.
+ *
+ * npm's default when no `--tag` is given is `latest`, which is the tag `npm
+ * install @knowzai/cli` resolves. Publishing `1.2.3-rc.1` with that default
+ * hands every user of the plain install command an unreleased build — and the
+ * only way back is to re-point `latest` at the previous version by hand.
+ *
+ * A release version keeps `latest`. A prerelease MUST name its own tag: the
+ * caller is the one that knows whether this is an `rc`, a `next`, or a `canary`,
+ * and a default here would just reintroduce the same silent choice one layer
+ * down. So a prerelease with no tag is an error, not a fallback.
+ */
+export declare function resolveDistTag(opts: {
+    version: string;
+    tag?: string;
+}): string;
+/** What to do with one package in a resumable publish run. */
+export type PublishAction = 'publish' | 'skip' | 'fail';
+export interface PublishStep {
+    action: PublishAction;
+    /** One line explaining the decision, safe to print verbatim. */
+    reason: string;
+    /** Non-empty only for `fail` — why the already-published copy is unusable. */
+    failures: string[];
+}
+/**
+ * H2 (resumability) — decide whether one package still needs publishing.
+ *
+ * A publish run is not atomic: eight packages go out one at a time, and a
+ * network blip, an OTP timeout, or a rate limit can strand the run halfway.
+ * Re-running used to be impossible — npm rejects a republish of an existing
+ * `name@version` with E403, so the retry died on the first already-published
+ * package and the remaining ones stayed unpublished. Recovering meant bumping
+ * every version for no reason.
+ *
+ * So an exact `name@version` that is ALREADY on the registry is not an error:
+ * it is work that is already done. It is verified against the same contract a
+ * fresh publish must satisfy (no `workspace:` leakage, internal deps pinned to
+ * the release version) and then skipped. A published copy that does NOT satisfy
+ * that contract is the one case that must stop the run — silently accepting it
+ * would ship a graph whose consumers cannot resolve.
+ *
+ * Pure so the script and the tests exercise identical logic; the caller owns the
+ * registry lookup and passes `null` for "not published".
+ */
+export declare function decidePublishStep(opts: {
+    name: string;
+    version: string;
+    /** Manifest of the exact `name@version` on the registry, or null if absent. */
+    registryManifest: PackageManifest | null | undefined;
+    internalNames: ReadonlySet<string>;
+}): PublishStep;
+//# sourceMappingURL=release-package-graph.d.ts.map

package/dist/lib/release-package-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-package-graph.d.ts","sourceRoot":"","sources":["../../src/lib/release-package-graph.ts"],"names":[],"mappings":"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"}