@jskit-ai/jskit-cli 0.2.126 → 0.2.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.126",
+  "version": "0.2.127",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.121",
-    "@jskit-ai/kernel": "0.1.114",
-    "@jskit-ai/shell-web": "0.1.113",
+    "@jskit-ai/jskit-catalog": "0.1.122",
+    "@jskit-ai/kernel": "0.1.115",
+    "@jskit-ai/shell-web": "0.1.114",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/cliRuntime/mutations/textMutations.js

@@ -29,6 +29,9 @@ import {
   resolveTemplateContextReplacementsForMutation
 } from "./templateContext.js";
 import { normalizeMutationRelativeFilePath } from "./mutationPathUtils.js";
+import {
+  isSensitiveTextMutation
+} from "../sensitiveLockState.js";
 
 const PRE_FILE_CONFIG_MUTATION_TARGETS = new Set([
   "config/public.js",
@@ -83,17 +86,27 @@ async function applyTextMutations(
       }
 
       const recordKey = `${relativeFile}::${String(mutation?.id || resolvedKey)}`;
-      managedText[recordKey] = {
+      const mutationIsSensitive = isSensitiveTextMutation({
+        packageEntry,
+        mutation,
+        resolvedKey
+      });
+      const managedRecord = {
         file: relativeFile,
         op: "upsert-env",
         key: resolvedKey,
-        value: resolvedValue,
         hadPrevious: upserted.hadPrevious,
-        previousValue: upserted.previousValue,
         reason: String(mutation?.reason || ""),
         category: String(mutation?.category || ""),
         id: String(mutation?.id || "")
       };
+      if (mutationIsSensitive) {
+        managedRecord.sensitive = true;
+      } else {
+        managedRecord.value = resolvedValue;
+        managedRecord.previousValue = upserted.previousValue;
+      }
+      managedText[recordKey] = managedRecord;
       touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
       continue;
     }
@@ -158,10 +171,15 @@ async function applyTextMutations(
       }
 
       const recordKey = `${relativeFile}::${mutationId}`;
+      const mutationIsSensitive = isSensitiveTextMutation({
+        packageEntry,
+        mutation,
+        resolvedKey: ""
+      });
       managedText[recordKey] = {
         file: relativeFile,
         op: "append-text",
-        value: renderedSnippet,
+        ...(mutationIsSensitive ? { sensitive: true } : { value: renderedSnippet }),
         position,
         reason: String(mutation?.reason || ""),
         category: String(mutation?.category || ""),

package/src/server/cliRuntime/packageInstallFlow.js

@@ -34,6 +34,9 @@ import {
 import {
   resolvePackageTemplateRoot
 } from "./packageTemplateResolution.js";
+import {
+  sanitizePackageOptionsForLock
+} from "./sensitiveLockState.js";
 import {
   applyFileMutations,
   applySourceMutations,
@@ -69,7 +72,7 @@ function createManagedRecordBase(packageEntry, options) {
       files: [],
       migrations: []
     },
-    options,
+    options: sanitizePackageOptionsForLock(packageEntry, options),
     installedAt: new Date().toISOString()
   };
 }
@@ -278,9 +281,7 @@ async function applyPackagePositioning({
     version: packageEntry.version,
     source: resolveManagedSourceRecord(packageEntry, existingInstall),
     managed: nextManaged,
-    options: {
-      ...ensureObject(packageOptions)
-    },
+    options: sanitizePackageOptionsForLock(packageEntry, packageOptions),
     installedAt: String(existingInstall.installedAt || new Date().toISOString())
   };
   lock.installedPackages[packageEntry.packageId] = managedRecord;
@@ -359,9 +360,7 @@ async function applyPackageMigrationsOnly({
     packageId: packageEntry.packageId,
     source: resolveManagedSourceRecord(packageEntry, existingInstall),
     managed: nextManaged,
-    options: {
-      ...ensureObject(packageOptions)
-    },
+    options: sanitizePackageOptionsForLock(packageEntry, packageOptions),
     migrationSyncVersion: packageEntry.version,
     installedAt: String(existingInstall.installedAt || new Date().toISOString())
   };

package/src/server/cliRuntime/sensitiveLockState.js

@@ -0,0 +1,234 @@
+import path from "node:path";
+import {
+  ensureArray,
+  ensureObject
+} from "../shared/collectionUtils.js";
+import {
+  escapeRegExp,
+  interpolateOptionValue,
+  isSecretOptionInput
+} from "../shared/optionInterpolation.js";
+import { parseEnvLineValue } from "./appState.js";
+
+const OPTION_REFERENCE_PATTERN = /\$\{option:([a-z][a-z0-9-]*)(\|[^}]*)?\}/gi;
+const SENSITIVE_NAME_PATTERN = /(^|[-_])(password|passwd|passphrase|secret|token|api[-_]?key|private[-_]?key|credential|credentials)([-_]|$)/i;
+
+function collectOptionReferences(value = "") {
+  return [
+    ...new Set(
+      [...String(value || "").matchAll(OPTION_REFERENCE_PATTERN)]
+        .map((match) => String(match[1] || "").trim())
+        .filter(Boolean)
+    )
+  ];
+}
+
+function isSensitiveName(value = "") {
+  return SENSITIVE_NAME_PATTERN.test(String(value || "").trim());
+}
+
+function isSensitivePackageOption(packageEntry = {}, optionName = "") {
+  const normalizedOptionName = String(optionName || "").trim();
+  if (!normalizedOptionName) {
+    return false;
+  }
+
+  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+  const optionSchema = ensureObject(optionSchemas[normalizedOptionName]);
+  return isSecretOptionInput(optionSchema) || isSensitiveName(normalizedOptionName);
+}
+
+function isSensitiveEnvKey(key = "") {
+  return isSensitiveName(String(key || "").trim().toLowerCase().replace(/_/g, "-"));
+}
+
+function textValueReferencesSensitiveOption(packageEntry = {}, value = "") {
+  return collectOptionReferences(value).some((optionName) =>
+    isSensitivePackageOption(packageEntry, optionName)
+  );
+}
+
+function isExactOptionReference(value = "", optionName = "") {
+  const pattern = new RegExp(`^\\s*\\$\\{option:${escapeRegExp(optionName)}\\}\\s*$`, "i");
+  return pattern.test(String(value || ""));
+}
+
+function isSensitiveTextMutation({ packageEntry = {}, mutation = {}, resolvedKey = "" } = {}) {
+  const mutationRecord = ensureObject(mutation);
+  if (mutationRecord.sensitive === true || mutationRecord.secret === true) {
+    return true;
+  }
+  if (String(mutationRecord.op || "").trim() === "upsert-env" && isSensitiveEnvKey(resolvedKey)) {
+    return true;
+  }
+  return textValueReferencesSensitiveOption(packageEntry, mutationRecord.value);
+}
+
+function isSensitiveManagedTextRecord({ packageEntry = {}, record = {} } = {}) {
+  const changeRecord = ensureObject(record);
+  if (changeRecord.sensitive === true || changeRecord.secret === true) {
+    return true;
+  }
+  if (String(changeRecord.op || "").trim() === "upsert-env" && isSensitiveEnvKey(changeRecord.key)) {
+    return true;
+  }
+  return textValueReferencesSensitiveOption(packageEntry, changeRecord.value);
+}
+
+function sanitizePackageOptionsForLock(packageEntry = {}, options = {}) {
+  const sanitized = {};
+  for (const [optionName, optionValue] of Object.entries(ensureObject(options))) {
+    if (isSensitivePackageOption(packageEntry, optionName)) {
+      continue;
+    }
+    sanitized[optionName] = optionValue;
+  }
+  return sanitized;
+}
+
+function sanitizePackageOptionsForResolve(packageEntry = {}, options = {}) {
+  return sanitizePackageOptionsForLock(packageEntry, options);
+}
+
+function sanitizeManagedTextForLock(packageEntry = {}, managedText = {}) {
+  const sanitized = {};
+  for (const [recordKey, rawRecord] of Object.entries(ensureObject(managedText))) {
+    const record = {
+      ...ensureObject(rawRecord)
+    };
+    if (isSensitiveManagedTextRecord({ packageEntry, record })) {
+      delete record.value;
+      delete record.previousValue;
+      record.sensitive = true;
+    }
+    sanitized[recordKey] = record;
+  }
+  return sanitized;
+}
+
+function sanitizeInstalledPackageRecordForLock(record = {}, packageEntry = {}) {
+  const installedRecord = ensureObject(record);
+  const managed = ensureObject(installedRecord.managed);
+  const sanitizedRecord = {
+    ...installedRecord,
+    options: sanitizePackageOptionsForLock(packageEntry, installedRecord.options)
+  };
+
+  if (Object.keys(managed).length > 0) {
+    sanitizedRecord.managed = {
+      ...managed,
+      text: sanitizeManagedTextForLock(packageEntry, managed.text)
+    };
+  }
+
+  return sanitizedRecord;
+}
+
+function sanitizeLockSecretsForWrite(lock = {}, packageRegistry = null) {
+  const lockRecord = ensureObject(lock);
+  const installedPackages = ensureObject(lockRecord.installedPackages);
+  for (const [packageId, installedRecord] of Object.entries(installedPackages)) {
+    const packageEntry = packageRegistry?.get?.(packageId) || {
+      packageId,
+      descriptor: {
+        options: {}
+      }
+    };
+    installedPackages[packageId] = sanitizeInstalledPackageRecordForLock(installedRecord, packageEntry);
+  }
+  lockRecord.installedPackages = installedPackages;
+  return lockRecord;
+}
+
+function readEnvValue(content = "", key = "") {
+  const lookupPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (const line of String(content || "").split(/\r?\n/)) {
+    if (lookupPattern.test(line)) {
+      return String(parseEnvLineValue(line, key) || "");
+    }
+  }
+  return null;
+}
+
+async function resolveSensitiveOptionEnvFallbacks({
+  packageEntry = {},
+  appRoot = "",
+  optionInput = {},
+  readFileBufferIfExists
+} = {}) {
+  if (!appRoot || typeof readFileBufferIfExists !== "function") {
+    return {};
+  }
+
+  const fallbacks = {};
+  const runtimeOptions = ensureObject(optionInput);
+  const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+  const textMutations = ensureArray(ensureObject(packageEntry?.descriptor?.mutations).text);
+
+  for (const mutation of textMutations) {
+    const mutationRecord = ensureObject(mutation);
+    if (String(mutationRecord.op || "").trim() !== "upsert-env") {
+      continue;
+    }
+
+    const relativeFile = String(mutationRecord.file || "").trim();
+    const rawKey = String(mutationRecord.key || "").trim();
+    if (!relativeFile || !rawKey) {
+      continue;
+    }
+
+    const sensitiveOptionNames = collectOptionReferences(mutationRecord.value)
+      .filter((optionName) => isSensitivePackageOption(packageEntry, optionName))
+      .filter((optionName) => !Object.prototype.hasOwnProperty.call(runtimeOptions, optionName));
+    if (sensitiveOptionNames.length !== 1) {
+      continue;
+    }
+
+    const optionName = sensitiveOptionNames[0];
+    if (!isExactOptionReference(mutationRecord.value, optionName)) {
+      continue;
+    }
+
+    let resolvedKey = "";
+    try {
+      resolvedKey = interpolateOptionValue(
+        rawKey,
+        runtimeOptions,
+        packageEntry.packageId,
+        `${rawKey}.key`
+      ).trim();
+    } catch {
+      continue;
+    }
+    if (!resolvedKey) {
+      continue;
+    }
+
+    const existing = await readFileBufferIfExists(path.join(appRoot, relativeFile));
+    if (!existing.exists) {
+      continue;
+    }
+
+    const envValue = readEnvValue(existing.buffer.toString("utf8"), resolvedKey);
+    const optionSchema = ensureObject(optionSchemas[optionName]);
+    if (envValue !== null && (envValue || optionSchema.allowEmpty === true)) {
+      fallbacks[optionName] = envValue;
+    }
+  }
+
+  return fallbacks;
+}
+
+export {
+  collectOptionReferences,
+  isSensitiveEnvKey,
+  isSensitiveManagedTextRecord,
+  isSensitivePackageOption,
+  isSensitiveTextMutation,
+  resolveSensitiveOptionEnvFallbacks,
+  sanitizeInstalledPackageRecordForLock,
+  sanitizeLockSecretsForWrite,
+  sanitizeManagedTextForLock,
+  sanitizePackageOptionsForLock,
+  sanitizePackageOptionsForResolve
+};

package/src/server/commandHandlers/packageCommands/add.js

@@ -6,6 +6,11 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  resolveSensitiveOptionEnvFallbacks,
+  sanitizeLockSecretsForWrite,
+  sanitizePackageOptionsForResolve
+} from "../../cliRuntime/sensitiveLockState.js";
 import {
   fileExists
 } from "../appCommands/shared.js";
@@ -162,6 +167,35 @@ async function installAppDependenciesForHook({
   }
 }
 
+async function resolvePackageOptionInputForInstall({
+  packageEntry,
+  existingInstall,
+  packageInlineOptions,
+  appRoot,
+  readFileBufferIfExists
+}) {
+  const lockOptions = sanitizePackageOptionsForResolve(
+    packageEntry,
+    ensureObject(existingInstall.options)
+  );
+  const inlineOptions = ensureObject(packageInlineOptions);
+  const optionInput = {
+    ...lockOptions,
+    ...inlineOptions
+  };
+  const secretEnvFallbacks = await resolveSensitiveOptionEnvFallbacks({
+    packageEntry,
+    appRoot,
+    optionInput,
+    readFileBufferIfExists
+  });
+  return {
+    ...lockOptions,
+    ...secretEnvFallbacks,
+    ...inlineOptions
+  };
+}
+
 function validateHookResult(result = {}, { packageId = "", hookLabel = "" } = {}) {
   if (typeof result === "undefined" || result === null) {
     return {};
@@ -327,6 +361,7 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
     applyPackageInstall,
     adoptAppLocalPackageDependencies,
     writeJsonFile,
+    readFileBufferIfExists,
     runNpmInstall,
     renderResolvedSummary,
     createCatalogFetchStatusReporter = () => () => {}
@@ -572,13 +607,16 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       : existingVersion === packageEntry.version
         ? "reapply"
         : "upgrade";
-    const lockEntryOptions = ensureObject(existingInstall.options);
+    const optionInput = await resolvePackageOptionInputForInstall({
+      packageEntry,
+      existingInstall,
+      packageInlineOptions,
+      appRoot,
+      readFileBufferIfExists
+    });
     resolvedOptionsByPackage[packageId] = await resolvePackageOptions(
       packageEntry,
-      {
-        ...lockEntryOptions,
-        ...packageInlineOptions
-      },
+      optionInput,
       io,
       { appRoot }
     );
@@ -759,6 +797,7 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   if (!options.dryRun) {
     await writeJsonFile(packageJsonPath, packageJson);
+    sanitizeLockSecretsForWrite(lock, combinedPackageRegistry);
     await writeJsonFile(lockPath, lock);
     if (options.runNpmInstall && !managesNpmInstall) {
       await runNpmInstall(appRoot, io.stderr);

package/src/server/commandHandlers/packageCommands/create.js

@@ -2,6 +2,9 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  sanitizeLockSecretsForWrite
+} from "../../cliRuntime/sensitiveLockState.js";
 
 async function runPackageCreateCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
@@ -111,6 +114,7 @@ async function runPackageCreateCommand(ctx = {}, { positional, options, cwd, io
   const touchedFileList = sortStrings([...touchedFiles]);
   if (!options.dryRun) {
     await writeJsonFile(packageJsonPath, packageJson);
+    sanitizeLockSecretsForWrite(lock);
     await writeJsonFile(lockPath, lock);
     if (options.runNpmInstall) {
       await runNpmInstall(appRoot, io.stderr);

package/src/server/commandHandlers/packageCommands/migrations.js

@@ -3,6 +3,11 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  resolveSensitiveOptionEnvFallbacks,
+  sanitizeLockSecretsForWrite,
+  sanitizePackageOptionsForResolve
+} from "../../cliRuntime/sensitiveLockState.js";
 
 async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
@@ -18,6 +23,7 @@ async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd,
     validateInlineOptionsForPackage,
     resolvePackageOptions,
     applyPackageMigrationsOnly,
+    readFileBufferIfExists,
     writeJsonFile
   } = ctx;
 
@@ -84,10 +90,22 @@ async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd,
     validateInlineOptionsForPackage(packageEntry, options.inlineOptions);
     const installedRecord = ensureObject(installedPackages[packageId]);
     const mergedInlineOptions = scope === "package" ? ensureObject(options.inlineOptions) : {};
+    const lockOptions = sanitizePackageOptionsForResolve(packageEntry, installedRecord.options);
+    const optionInput = {
+      ...lockOptions,
+      ...mergedInlineOptions
+    };
+    const secretEnvFallbacks = await resolveSensitiveOptionEnvFallbacks({
+      packageEntry,
+      appRoot,
+      optionInput,
+      readFileBufferIfExists
+    });
     const resolvedOptions = await resolvePackageOptions(
       packageEntry,
       {
-        ...ensureObject(installedRecord.options),
+        ...lockOptions,
+        ...secretEnvFallbacks,
         ...mergedInlineOptions
       },
       io,
@@ -114,6 +132,7 @@ async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd,
 
   const touchedFileList = sortStrings([...touchedFiles]);
   if (!options.dryRun) {
+    sanitizeLockSecretsForWrite(lock, combinedPackageRegistry);
     await writeJsonFile(lockPath, lock);
   }
 

package/src/server/commandHandlers/packageCommands/position.js

@@ -2,6 +2,11 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  resolveSensitiveOptionEnvFallbacks,
+  sanitizeLockSecretsForWrite,
+  sanitizePackageOptionsForResolve
+} from "../../cliRuntime/sensitiveLockState.js";
 
 async function runPackagePositionCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
@@ -17,6 +22,7 @@ async function runPackagePositionCommand(ctx = {}, { positional, options, cwd, i
     validateInlineOptionsForPackage,
     resolvePackageOptions,
     applyPackagePositioning,
+    readFileBufferIfExists,
     writeJsonFile
   } = ctx;
 
@@ -51,11 +57,24 @@ async function runPackagePositionCommand(ctx = {}, { positional, options, cwd, i
   validateInlineOptionsForPackage(packageEntry, options.inlineOptions);
 
   const installedRecord = ensureObject(installedPackages[resolvedTargetId]);
+  const lockOptions = sanitizePackageOptionsForResolve(packageEntry, installedRecord.options);
+  const inlineOptions = ensureObject(options.inlineOptions);
+  const optionInput = {
+    ...lockOptions,
+    ...inlineOptions
+  };
+  const secretEnvFallbacks = await resolveSensitiveOptionEnvFallbacks({
+    packageEntry,
+    appRoot,
+    optionInput,
+    readFileBufferIfExists
+  });
   const resolvedOptions = await resolvePackageOptions(
     packageEntry,
     {
-      ...ensureObject(installedRecord.options),
-      ...ensureObject(options.inlineOptions)
+      ...lockOptions,
+      ...secretEnvFallbacks,
+      ...inlineOptions
     },
     io,
     { appRoot }
@@ -72,6 +91,7 @@ async function runPackagePositionCommand(ctx = {}, { positional, options, cwd, i
   const touchedFileList = sortStrings([...touchedFiles]);
 
   if (!options.dryRun) {
+    sanitizeLockSecretsForWrite(lock, combinedPackageRegistry);
     await writeJsonFile(lockPath, lock);
   }
 

package/src/server/commandHandlers/packageCommands/remove.js

@@ -3,6 +3,10 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  isSensitiveManagedTextRecord,
+  sanitizeLockSecretsForWrite
+} from "../../cliRuntime/sensitiveLockState.js";
 
 async function runPackageRemoveCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
@@ -61,6 +65,12 @@ async function runPackageRemoveCommand(ctx = {}, { positional, options, cwd, io
   }
 
   const lockEntry = ensureObject(installed[resolvedTargetId]);
+  const packageEntry = combinedPackageRegistry.get(resolvedTargetId) || {
+    packageId: resolvedTargetId,
+    descriptor: {
+      options: {}
+    }
+  };
   const managed = ensureObject(lockEntry.managed);
   const touchedFiles = new Set();
 
@@ -87,6 +97,9 @@ async function runPackageRemoveCommand(ctx = {}, { positional, options, cwd, io
     if (String(changeRecord.op || "") !== "upsert-env") {
       continue;
     }
+    if (isSensitiveManagedTextRecord({ packageEntry, record: changeRecord })) {
+      continue;
+    }
     const relativeFile = String(changeRecord.file || "").trim();
     if (!relativeFile) {
       continue;
@@ -150,6 +163,7 @@ async function runPackageRemoveCommand(ctx = {}, { positional, options, cwd, io
 
   if (!options.dryRun) {
     await writeJsonFile(packageJsonPath, packageJson);
+    sanitizeLockSecretsForWrite(lock, combinedPackageRegistry);
     await writeJsonFile(lockPath, lock);
     if (options.runNpmInstall) {
       await runNpmInstall(appRoot, io.stderr);

package/src/server/core/commandCatalog.js

@@ -540,7 +540,8 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "No npm install runs unless --run-npm-install is passed.",
-      "Existing lock options are reused unless overridden inline.",
+      "Existing non-secret lock options are reused unless overridden inline.",
+      "Secret options are read from current .env values or explicit inline options; they are not stored in the lock.",
       "update reuses add package flow with forced reapply."
     ]),
     fullUse: "jskit update package <packageId> [--<option> <value>...] [--dry-run] [--run-npm-install] [--json]",

package/src/server/shared/optionInterpolation.js

@@ -525,6 +525,7 @@ export {
   appendTextSnippet,
   escapeRegExp,
   interpolateOptionValue,
+  isSecretOptionInput,
   normalizeSkipChecks,
   promptForRequiredOption
 };