@descix/cli 1.0.5 → 1.0.7

package/lib/commands/config.js

@@ -9,6 +9,8 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { WorkspaceConfig } from '../workspace-config.js';
 import { environmentNameFor } from '../environment-report.js';
+import { resolveEffectiveOrigin } from '../api-client.js';
+import { normalizeOrigin } from '../origin.js';
 
 /**
  * Show current configuration
@@ -20,15 +22,17 @@ export async function show() {
 
     console.log(chalk.cyan('\n📋 DeSciX Workspace Configuration:\n'));
     console.log(chalk.white(`   Workspace:     ${workspaceRoot}`));
-    // Under (A', contract rev 2) getApiUrl() ALWAYS yields an origin — a workspace that named
-    // none resolves to the declared default. The "(not configured)" branch is therefore
-    // unreachable and was DELETED, not fenced.
-    const configuredOrigin = workspaceConfig.getApiUrl();
-    console.log(chalk.white(`   API URL:       ${configuredOrigin}`));
-    // The environment NAME comes from the ONE owner that derives it from the origin. It used to
-    // read a separate `env.environment` key and fall back to the literal 'production' — a second
-    // derivation of the same fact, which could disagree with the origin printed one line above.
-    console.log(chalk.white(`   Environment:   ${environmentNameFor(configuredOrigin)}`));
+    // The origin every command in this shell will USE, and who chose it — not the file's value
+    // alone. An inherited DESCIX_API_URL outranks the workspace pin; showing only the pin made
+    // `config show` say dev while commands ran against production.
+    const effective = await resolveEffectiveOrigin(workspaceConfig.env?.apiUrl);
+    console.log(chalk.white(`   API URL:       ${effective.origin}`));
+    console.log(chalk.white(`   Environment:   ${environmentNameFor(effective.origin)}`));
+    console.log(chalk.white(`   Chosen by:     ${effective.source}`));
+    const pinned = workspaceConfig.env?.apiUrl;
+    if (pinned && normalizeOrigin(pinned) !== effective.origin) {
+      console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
+    }
 
     // Show mapped apps (v2.1 env.products)
     const platform = workspaceConfig.env?.platform;
@@ -49,28 +53,6 @@ export async function show() {
   }
 }
 
-/**
- * Set API URL
- */
-export async function setUrl(url, options = {}) {
-  try {
-    const workspaceConfig = await WorkspaceConfig.load();
-    const workspaceRoot = workspaceConfig.getWorkspaceRoot();
-
-    workspaceConfig.apiUrl = url;
-    workspaceConfig.environment = url.includes('localhost') ? 'development' : 'production';
-    const configPath = await workspaceConfig.save(workspaceRoot);
-
-    console.log(chalk.green('\n✅ Configuration updated!\n'));
-    console.log(chalk.white(`   API URL: ${url}`));
-    console.log(chalk.gray(`   Saved to: ${configPath}\n`));
-
-  } catch (error) {
-    console.error(chalk.red('Error updating config:', error.message));
-    throw error;
-  }
-}
-
 /**
  * Initialize config for environment
  */

package/lib/commands/corpus.js

@@ -27,7 +27,10 @@ import { WorkspaceConfig } from '../workspace-config.js';
 import { loadManifests } from '../core/ManifestLoader.js';
 import { walkCorpus } from '../core/CorpusWalker.js';
 import { chunkFile, categorizeFile } from '../core/Chunker.js';
-import { upsertChunks, deleteStaleChunks, deleteStaleChunksByFileId, listRemoteFileIds, purgeKbScope } from '../core/Syncer.js';
+import {
+  upsertChunks, deleteStaleChunks, deleteStaleChunksByFileId, listRemoteFileIds, purgeKbScope,
+  isReportedCount, accumulateReportedCount, UNREPORTED_COUNT
+} from '../core/Syncer.js';
 import { lintManifestForDenyClasses, assertNoViolations } from '../core/CorpusDenyLint.js';
 
 /**
@@ -151,6 +154,57 @@ async function chunkCorpusFile(fileEntry, context) {
   }).filter(Boolean);
 }
 
+/**
+ * Read the previously-synced chunk total out of sync state, for REPORTING only.
+ *
+ * Three states must not be conflated:
+ *   no sync state at all      -> 0, a fact about US (we have never synced), not the store
+ *   total_chunks is a number  -> that number, INCLUDING a legitimate 0
+ *   total_chunks null/absent  -> null: UNKNOWN, and said so. It is never coerced to 0.
+ *
+ * The file delta is computed from blob SHAs, never from this number, so an unknown
+ * previous total blocks nothing. The total is re-established on every clean sync by the
+ * store's own live read-back (`liveTotalFromReconcile`), never by arithmetic on it.
+ *
+ * @param {Object|null} previousState - the loaded sync state, or null on first sync
+ * @returns {number|null}
+ */
+export function readPreviousChunkCount(previousState) {
+  if (!previousState) return 0;
+  return Number.isFinite(previousState.total_chunks) ? previousState.total_chunks : null;
+}
+
+/**
+ * The chunk total to PERSIST: the store's MEASURED live count from the post-sync
+ * reconcile (`get_kb_rag_status {reconcile:true}` → `reconcileAfter`), or null when the
+ * store reported none. This is the ONE owner of `total_chunks`.
+ *
+ * Why not previous + upserted − deleted: the server's `kb_sync_chunks` answers
+ * `upserted_count: null` by ruling (Pinecone's upsert API returns no count) and publishes
+ * the measured `rag_vector_count` instead. An arithmetic total built on that null was null
+ * on every sync, including `--rebuild` (measured 2026-09-16: reconcile read 6882 live and
+ * the state still said unknown), so the "re-run with --rebuild" remedy was a loop.
+ *
+ * @param {Object|null|undefined} rec - the reconcile response's message
+ * @returns {number|null}
+ */
+export function liveTotalFromReconcile(rec) {
+  return Number.isFinite(rec?.reconcileAfter) ? rec.reconcileAfter : null;
+}
+
+/**
+ * Render a count for display: the number when the store reported it, otherwise a
+ * phrase that says so. Consumes the module's count owner rather than re-testing
+ * `>= 0` at each call site.
+ *
+ * @param {number} value
+ * @param {string} unknownText
+ * @returns {string}
+ */
+export function renderCount(value, unknownText = 'an unreported number of') {
+  return isReportedCount(value) ? String(value) : unknownText;
+}
+
 /**
  * Save sync state after a successful corpus sync.
  *
@@ -268,15 +322,21 @@ function resolveRef(manifest, cliRef) {
  * @returns {Promise<boolean>}
  */
 async function confirmYesNo(prompt) {
-  const readline = await import('readline');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => {
-    rl.question(`${prompt} [y/N] `, answer => {
-      rl.close();
-      const a = (answer || '').trim().toLowerCase();
-      resolve(a === 'y' || a === 'yes');
-    });
+  // Gated at construction by the ONE owner of "may I prompt". Under a non-TTY this throws a
+  // loud NonInteractiveError instead of hanging (open pipe/FIFO) or resolving nothing (/dev/null).
+  const { createPromptSession } = await import('../interactive.js');
+  const rl = createPromptSession({
+    what: 'descix kb corpus',
+    destructive: true,
+    nonInteractiveForm: ['descix kb corpus ... --yes   # skips this confirmation']
   });
+  try {
+    const answer = await rl.askRaw(`${prompt} [y/N] `);
+    const a = (answer || '').trim().toLowerCase();
+    return a === 'y' || a === 'yes';
+  } finally {
+    rl.close();
+  }
 }
 
 /**
@@ -455,9 +515,18 @@ export async function runCorpusSync(apiClient, options) {
 
       // 3a. Walk corpus
       const walkSpinner = ora('  Walking source directories...').start();
-      const { files, commitSha, provenance } = await walkCorpus(manifest, workspaceRoot);
+      const { files, commitSha, provenance, gateBoundary } = await walkCorpus(manifest, workspaceRoot);
       walkSpinner.succeed(`  Found ${files.length} files (commit: ${commitSha.substring(0, 8)})`);
 
+      // A gate prints its own COVERAGE BOUNDARY with its verdict — on GREEN as well as
+      // RED — so the reader of a pass can see where the pass stops without hunting for a
+      // report elsewhere. Every file above cleared the source gate.
+      console.log(chalk.gray(`  [source-gate] PASS — all ${files.length} file(s) tracked by git at their manifest ref.`));
+      console.log(chalk.gray(`  [source-gate] compares: ${gateBoundary.compares}`));
+      console.log(chalk.gray(`  [source-gate] catches: ${gateBoundary.catches}`));
+      console.log(chalk.gray(`  [source-gate] does NOT read: ${gateBoundary.does_not_read}`));
+      console.log(chalk.gray(`  [source-gate] runs automatically: ${gateBoundary.runs_automatically}`));
+
       // ── Deliverable A: --show-walk prints the resolved ref + first 50 files
       // BEFORE any Pinecone read/write so the operator can sanity-check the
       // walk results without trusting downstream output.
@@ -507,9 +576,13 @@ export async function runCorpusSync(apiClient, options) {
           const remote = await listRemoteFileIds(apiClient, appId, kbName);
           rebuildRemoteUniqueCount = remote.unique_count;
           rebuildRemoteTotalChunks = remote.total_chunks;
+          // `Pinecone reports N` is an ATTRIBUTION to the store, so it may only carry
+          // numbers the store actually reported. The file_ids list is always real
+          // (listRemoteFileIds throws rather than fabricating it); the counts may not be.
           rebuildSpinner.succeed(
-            `  [rebuild] Pinecone reports ${remote.unique_count} corpus-scheme file_id(s) / ` +
-            `${remote.total_chunks} enumerable chunk(s) (legacy orphans may exceed this)`
+            `  [rebuild] Pinecone enumerated ${remote.file_ids.length} corpus-scheme file_id(s); ` +
+            `reports ${renderCount(remote.unique_count)} unique / ` +
+            `${renderCount(remote.total_chunks)} enumerable chunk(s) (legacy orphans may exceed this)`
           );
 
           if (options.dryRun) {
@@ -521,9 +594,13 @@ export async function runCorpusSync(apiClient, options) {
             ));
           } else {
             // Interactive confirmation guard. --yes skips for scripting/CI.
+            // A destructive-action prompt must not overstate its own certainty: if the
+            // store reported no count, say so rather than printing "≥-1".
             console.log(chalk.yellow(
               `\n  About to FULL-SCOPE PURGE every vector in ${communityId}/${appId}/${kbName} ` +
-              `(≥${rebuildRemoteTotalChunks} enumerable chunk(s); legacy orphans included), ` +
+              (isReportedCount(rebuildRemoteTotalChunks)
+                ? `(≥${rebuildRemoteTotalChunks} enumerable chunk(s); legacy orphans included), `
+                : `(the store reported no chunk count; ALL vectors in scope will go), `) +
               `then re-upsert the full local walk (${files.length} file(s)).`
             ));
 
@@ -544,9 +621,9 @@ export async function runCorpusSync(apiClient, options) {
               rebuildScopePurged = purgeResult.purged_scope;
               // deleteRAG via filter-based deleteMany returns -1 (count not knowable
               // from the SDK). Surface honestly rather than fabricating a number.
-              rebuildPurged = purgeResult.deleted >= 0 ? purgeResult.deleted : 0;
+              rebuildPurged = purgeResult.deleted;
               purgeSpinner.succeed(
-                purgeResult.deleted >= 0
+                isReportedCount(purgeResult.deleted)
                   ? `  [rebuild] Purged ${purgeResult.deleted} vector(s) (full scope) and reset KB doc rag fields`
                   : `  [rebuild] Purged full scope (filter-based delete; SDK reports no count) and reset KB doc rag fields`
               );
@@ -574,10 +651,10 @@ export async function runCorpusSync(apiClient, options) {
         previousState = null;
       }
       const previousBlobShas = new Set(previousState?.synced_blob_shas || []);
-      const previousChunkCount = previousState?.total_chunks || 0;
+      const previousChunkCount = readPreviousChunkCount(previousState);
 
       if (previousBlobShas.size > 0) {
-        console.log(chalk.gray(`  Previous sync: ${previousBlobShas.size} files, ${previousChunkCount} chunks`));
+        console.log(chalk.gray(`  Previous sync: ${previousBlobShas.size} files, ${previousChunkCount ?? 'an unknown number of'} chunks`));
       } else {
         console.log(chalk.gray('  First sync (no previous state)'));
       }
@@ -640,7 +717,12 @@ export async function runCorpusSync(apiClient, options) {
         console.log(chalk.white(`    Would upsert: ${allChunks.length} chunks from ${newOrChangedFiles.length} file(s)`));
         console.log(chalk.white(`    Would delete (stale-file): ${fileIdsToDelete.length} blob SHA(s)`));
         if (options.rebuild) {
-          console.log(chalk.white(`    Would purge (rebuild): FULL scope ${communityId}/${appId}/${kbName} (≥${rebuildRemoteTotalChunks} enumerable chunks; legacy orphans included)`));
+          console.log(chalk.white(
+            `    Would purge (rebuild): FULL scope ${communityId}/${appId}/${kbName} ` +
+            (isReportedCount(rebuildRemoteTotalChunks)
+              ? `(≥${rebuildRemoteTotalChunks} enumerable chunks; legacy orphans included)`
+              : `(the store reported no chunk count; all vectors in scope)`)
+          ));
         }
         // Track for the summary exit-code computation at the end of the loop.
         totalFilesProcessed += newOrChangedFiles.length;
@@ -648,7 +730,10 @@ export async function runCorpusSync(apiClient, options) {
         totalFilesSkipped += unchangedCount;
         // Full-scope rebuild would purge ≥ the enumerable chunk count. Use it as the
         // would-delete tally so dry-run reports drift whenever a purge would run.
-        totalFilesDeleted += fileIdsToDelete.length + (options.rebuild ? rebuildRemoteTotalChunks : 0);
+        // Only add a rebuild figure the store actually reported; an unknown count
+        // contributes nothing rather than silently subtracting one from the total.
+        totalFilesDeleted += fileIdsToDelete.length +
+          ((options.rebuild && isReportedCount(rebuildRemoteTotalChunks)) ? rebuildRemoteTotalChunks : 0);
         // Do NOT call upsertChunks, deleteStaleChunksByFileId, deleteStaleChunks,
         // or saveSyncState in dry-run. Continue to next manifest.
         continue;
@@ -675,7 +760,9 @@ export async function runCorpusSync(apiClient, options) {
           while (!success && retries < MAX_RETRIES) {
             try {
               const result = await upsertChunks(apiClient, communityId, appId, kbName, batch);
-              upserted += result.upserted;
+              // Unknown-ness survives the running total: one unreportable batch makes
+              // the whole figure unstateable rather than quietly summing around it.
+              upserted = accumulateReportedCount(upserted, result.upserted);
               success = true;
               syncSpinner.text = `  Upserting chunks... ${i + batch.length}/${allChunks.length}`;
             } catch (err) {
@@ -715,7 +802,7 @@ export async function runCorpusSync(apiClient, options) {
           if (!success) {
             syncSpinner.warn(
               `  Batch ${i}-${i + batch.length} did not complete after ${MAX_RETRIES} retries. ` +
-              `Synced ${upserted} chunks so far. This run is BOUNDED (it did not hang) — ` +
+              `Synced ${renderCount(upserted)} chunks so far. This run is BOUNDED (it did not hang) — ` +
               `re-run 'descix kb corpus sync -a ${appId} -k ${kbName}' to RESUME: id-keyed upserts ` +
               `are idempotent so already-synced batches are cheap and the remainder continues.`
             );
@@ -728,7 +815,7 @@ export async function runCorpusSync(apiClient, options) {
           }
         }
 
-        syncSpinner.succeed(`  Upserted: ${upserted} chunks`);
+        syncSpinner.succeed(`  Upserted: ${renderCount(upserted)} chunks`);
 
         // Write failure log to .descix if any batches failed
         if (syncFailures.length > 0) {
@@ -752,59 +839,76 @@ export async function runCorpusSync(apiClient, options) {
           // (community_id, app_id, knowledgebase_name) — guarantees namespace isolation.
           const result = await deleteStaleChunksByFileId(apiClient, communityId, appId, kbName, fileIdsToDelete);
           deleted = result.deleted;
-          deleteSpinner.succeed(`  Purged: ${deleted} chunk(s) across ${fileIdsToDelete.length} stale blob SHA(s)`);
+          deleteSpinner.succeed(
+            `  Purged: ${renderCount(deleted)} chunk(s) across ${fileIdsToDelete.length} stale blob SHA(s)`
+          );
         } catch (err) {
-          deleteSpinner.warn(`  Delete failed: ${err.message}`);
+          // The purge ERRORED: how many were removed is unknown. Leaving `deleted` at 0
+          // would persist "nothing was deleted" into sync state as though it were a fact.
+          deleted = UNREPORTED_COUNT;
+          deleteSpinner.warn(`  Delete failed (deleted count unknown): ${err.message}`);
         }
       }
 
-      // 3f. Save sync state with blob SHAs for future delta computation
-      const allSyncedBlobShas = [...localBlobShas]; // All current files
-      await saveSyncState(appRoot, kbName, {
-        last_sync_commit: commitSha,
-        // Per-source provenance: WHICH repo, at WHICH ref, and the RESOLVED COMMIT SHA actually
-        // synced. `ref` may be a mutable branch, so the ref alone is not a record of what was
-        // synced — the resolved sha is, and it stays exact after the branch moves.
-        sources_provenance: provenance,
-        synced_files_count: files.length,
-        total_chunks: previousChunkCount + upserted - deleted,
-        timestamp: new Date().toISOString(),
-        files_upserted: newOrChangedFiles.length,
-        files_unchanged: unchangedCount,
-        chunks_upserted: upserted,
-        chunks_deleted: deleted,
-        synced_blob_shas: allSyncedBlobShas
-      });
-
-      // 3g. AUTO-RECONCILE the cached rag_vector_count to the TRUE live Pinecone
+      // 3f. AUTO-RECONCILE the cached rag_vector_count to the TRUE live Pinecone
       // count after a COMPLETED, clean sync (no batch failures). This keeps the
       // doctor's fast cached read truthful after every clean run, so drift only
       // ever appears mid-flight (on interruption). Skipped if any batch failed
       // (the run is partial — reconciling would bake in the partial state and the
       // re-run will reconcile once complete). Non-fatal: a reconcile hiccup must
-      // not fail an otherwise-successful sync.
+      // not fail an otherwise-successful sync — but then the persisted total is
+      // null, honestly, because nothing measured it.
+      let liveTotal = null;
       if (syncFailures.length === 0) {
         try {
           const recRes = await apiClient.invoke('get_kb_rag_status', {
             app_id: appId, kb_id: kbName, reconcile: true
           }, { allowGuest: false });
           const rec = recRes.message || recRes;
-          if (rec && typeof rec.reconcileAfter === 'number') {
+          liveTotal = liveTotalFromReconcile(rec);
+          if (liveTotal !== null) {
             const d = rec.reconcileAfter - rec.reconcileBefore;
             console.log(chalk.gray(
               `  ⟳ Reconciled live count: cached ${rec.reconcileBefore} → live ${rec.reconcileAfter}` +
               (d === 0 ? ' (already truthful)' : ` (${d >= 0 ? '+' : ''}${d})`)
             ));
+          } else {
+            console.log(chalk.yellow('  ⚠ Reconcile reported no live count; total_chunks stays unknown'));
           }
         } catch (recErr) {
           console.log(chalk.yellow(`  ⚠ Auto-reconcile skipped (non-fatal): ${recErr.message}`));
         }
       }
 
+      // 3g. Save sync state with blob SHAs for future delta computation
+      const allSyncedBlobShas = [...localBlobShas]; // All current files
+      await saveSyncState(appRoot, kbName, {
+        last_sync_commit: commitSha,
+        // Per-source provenance: WHICH repo, at WHICH ref, and the RESOLVED COMMIT SHA actually
+        // synced. `ref` may be a mutable branch, so the ref alone is not a record of what was
+        // synced — the resolved sha is, and it stays exact after the branch moves.
+        sources_provenance: provenance,
+        synced_files_count: files.length,
+        // The store's measured live count, or null — never a fabricated integer: this file
+        // is read by later runs, so a wrong number here outlives the console line.
+        total_chunks: liveTotal,
+        timestamp: new Date().toISOString(),
+        files_upserted: newOrChangedFiles.length,
+        files_unchanged: unchangedCount,
+        chunks_upserted: isReportedCount(upserted) ? upserted : null,
+        chunks_deleted: isReportedCount(deleted) ? deleted : null,
+        synced_blob_shas: allSyncedBlobShas
+      });
+
       totalFilesProcessed += newOrChangedFiles.length;
-      totalChunksCreated += upserted;
       totalFilesSkipped += unchangedCount;
-      totalFilesDeleted += deleted + rebuildPurged;
+      // A run total is summed by the SAME owner the per-batch total uses (:754), so an
+      // unreported leg leaves the total unstateable instead of quietly summing around it.
+      // Contributing 0 keeps -1 out of the printed total by fabricating a number in its
+      // place — the same untruth, told where nobody can see it.
+      totalChunksCreated = accumulateReportedCount(totalChunksCreated, upserted);
+      totalFilesDeleted = accumulateReportedCount(totalFilesDeleted, deleted);
+      totalFilesDeleted = accumulateReportedCount(totalFilesDeleted, rebuildPurged);
     }
 
     // Summary
@@ -827,13 +931,12 @@ export async function runCorpusSync(apiClient, options) {
 
     console.log(chalk.green('\nCorpus sync complete:'));
     console.log(chalk.white(`  Files synced:    ${totalFilesProcessed}`));
-    console.log(chalk.white(`  Chunks created:  ${totalChunksCreated}`));
+    console.log(chalk.white(`  Chunks created:  ${renderCount(totalChunksCreated)}`));
     console.log(chalk.white(`  Files unchanged: ${totalFilesSkipped}`));
-    if (totalFilesDeleted > 0) {
-      console.log(chalk.white(`  Chunks deleted:  ${totalFilesDeleted}`));
-    } else {
-      console.log(chalk.gray(`  Chunks deleted:  0`));
-    }
+    // Only a zero the store actually REPORTED is dimmed as a no-op; an unreported total
+    // is stated as unknown in full white, never collapsed into the "nothing happened" line.
+    const deletedLine = `  Chunks deleted:  ${renderCount(totalFilesDeleted)}`;
+    console.log(totalFilesDeleted === 0 ? chalk.gray(deletedLine) : chalk.white(deletedLine));
     console.log('');
     return { dryRun: false };
 
@@ -917,7 +1020,11 @@ export async function runCorpusStatus(apiClient, options) {
       console.log(chalk.white(`  Last sync:       ${syncState.timestamp}`));
       console.log(chalk.white(`  Commit:          ${syncState.last_sync_commit?.substring(0, 8) || 'unknown'}`));
       console.log(chalk.white(`  Files tracked:   ${syncState.synced_files_count}`));
-      console.log(chalk.white(`  Chunks in store: ${syncState.total_chunks}`));
+      console.log(chalk.white(
+        `  Chunks in store: ${Number.isFinite(syncState.total_chunks)
+          ? syncState.total_chunks
+          : 'unknown (the last sync reported no live count)'}`
+      ));
 
       // Quick change detection: walk and compare blob SHAs
       if (options.verbose) {