@notis_ai/cli 0.2.15 → 0.2.17

package/src/command-specs/apps.js

@@ -8,7 +8,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
@@ -36,6 +36,7 @@ import {
   normalizeAppCapabilities,
   normalizeAppToolBindings,
   normalizeAppSkillManifestPath,
+  appRowFieldsFromManifest,
   directDeploy,
   pullAppSource,
 } from '../runtime/app-platform.js';
@@ -45,6 +46,7 @@ import {
   scaffoldRegistryLabel,
 } from '../runtime/app-registry-scaffolds.js';
 import { startAppDevServer } from '../runtime/app-dev-server.js';
+import { captureDesktopHostOwnership } from '../runtime/app-dev-process-identity.js';
 import {
   discoverRegisteredAppProjects,
   readAppDevRoots,
@@ -87,6 +89,8 @@ import {
   toolConflictToError,
 } from './helpers.js';
 
+export { appRowFieldsFromManifest } from '../runtime/app-platform.js';
+
 const DEFAULT_DEV_PORT = 5173;
 const DEV_HEARTBEAT_INTERVAL_MS = 10_000;
 const DEV_CONSUMER_HEARTBEAT_INTERVAL_MS = 3_000;
@@ -98,6 +102,72 @@ function projectIsWithinRoot(projectDir, rootDir) {
   return nested === '' || (nested !== '..' && !nested.startsWith(`..${sep}`) && !isAbsolute(nested));
 }
 
+function parseNotisAppVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+    String(value || '').trim(),
+  );
+  if (!match) return null;
+  const prerelease = match[4] ? match[4].split('.') : [];
+  if (prerelease.some((identifier) => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))) {
+    return null;
+  }
+  return {
+    major: match[1],
+    minor: match[2],
+    patch: match[3],
+    prerelease,
+  };
+}
+
+function compareNumericSemverIdentifiers(left, right) {
+  if (left.length !== right.length) return left.length > right.length ? 1 : -1;
+  return left === right ? 0 : left > right ? 1 : -1;
+}
+
+function compareNotisPrerelease(left, right) {
+  if (left.length === 0 || right.length === 0) {
+    return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  }
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftIdentifier = left[index];
+    const rightIdentifier = right[index];
+    if (leftIdentifier === undefined || rightIdentifier === undefined) {
+      return leftIdentifier === rightIdentifier ? 0 : leftIdentifier === undefined ? -1 : 1;
+    }
+    if (leftIdentifier === rightIdentifier) continue;
+    const leftNumeric = /^\d+$/.test(leftIdentifier);
+    const rightNumeric = /^\d+$/.test(rightIdentifier);
+    if (leftNumeric && rightNumeric) {
+      return compareNumericSemverIdentifiers(leftIdentifier, rightIdentifier);
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftIdentifier > rightIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+
+export function compareNotisAppVersions(leftValue, rightValue) {
+  const left = parseNotisAppVersion(leftValue);
+  const right = parseNotisAppVersion(rightValue);
+  if (!left || !right) return null;
+  for (const key of ['major', 'minor', 'patch']) {
+    const comparison = compareNumericSemverIdentifiers(left[key], right[key]);
+    if (comparison !== 0) return comparison;
+  }
+  return compareNotisPrerelease(left.prerelease, right.prerelease);
+}
+
+function readLocalNotisAppVersion(projectDir) {
+  try {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+    const version = String(packageJson.notisAppVersion || '').trim();
+    return parseNotisAppVersion(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A CLI launch may add one root, but the shared host always serves the complete
  * machine registry. Desktop sets skipRootRegistration because it is reconciling
@@ -410,13 +480,6 @@ export function screenshotIndexByRouteSlug(manifest) {
   return new Map(routes.map((route, index) => [route.slug, index + 1]));
 }
 
-export function appRowFieldsFromManifest(manifest) {
-  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
-  return {
-    accent: app.accent ?? null,
-  };
-}
-
 export function screenshotExitCode(failedCount) {
   return failedCount === 0 ? EXIT_CODES.ok : EXIT_CODES.unexpected;
 }
@@ -570,7 +633,7 @@ function renderVerifyReport({ summary, results, noBrowser }) {
   return lines.join('\n');
 }
 
-function buildManifestForDev(appConfig) {
+function buildManifestForDev(appConfig, projectDir) {
   const routes = Array.isArray(appConfig.routes) ? appConfig.routes : [];
   return {
     version: 1,
@@ -579,6 +642,7 @@ function buildManifestForDev(appConfig) {
       name: appConfig.name,
       description: appConfig.description || null,
       icon: appConfig.icon || null,
+      release_version: readLocalNotisAppVersion(projectDir),
     },
     routes: routes.map((route) => ({
       path: route.path,
@@ -587,6 +651,7 @@ function buildManifestForDev(appConfig) {
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: route.default || false,
+      resourceDeepLinks: route.resourceDeepLinks === true,
       export_name: route.exportName || route.export_name,
       collection: route.collection || null,
     })),
@@ -726,7 +791,7 @@ export async function ensureDevInstall({
     throw usageError(`notis.config.ts devSlug or name in ${projectDir} must slugify to a non-empty value.`);
   }
 
-  const manifest = buildManifestForDev(appConfig);
+  const manifest = buildManifestForDev(appConfig, projectDir);
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   const profileKey = linkedStateProfileKey(ctx.runtime);
   let linkedState = readLinkedState(projectDir, profileKey);
@@ -801,6 +866,10 @@ export async function ensureDevInstall({
         ].includes(key)),
       )
     : linkedState;
+  const localReleaseVersion = manifest.app.release_version || null;
+  const installedReleaseVersion = linkedApp?.manifest?.app?.release_version || '0.0.0';
+  const mountEligible = !linkedApp
+    || compareNotisAppVersions(localReleaseVersion, installedReleaseVersion) === 1;
   const ensureArguments = buildEnsureDevInstallArguments({
     appConfig,
     manifest,
@@ -866,6 +935,9 @@ export async function ensureDevInstall({
     linkedAppId: runtimeLinkedState?.app_id || null,
     targetAppId: runtimeLinkedState?.app_id || null,
     targetAppSlug: linkedApp?.slug || null,
+    localReleaseVersion,
+    installedReleaseVersion: linkedApp ? installedReleaseVersion : null,
+    mountEligible,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
     liveData: ensureResult.payload.live_data || null,
   };
@@ -892,6 +964,16 @@ function liveDataWarnings(apps) {
     .map((app) => `${app.name}: ${app.liveData.warning}`);
 }
 
+function versionPrecedenceWarnings(apps) {
+  return apps
+    .filter((app) => app.targetAppId && app.mountEligible === false)
+    .map((app) => {
+      const localVersion = app.localReleaseVersion || 'missing or invalid';
+      const pullCommand = `npx --package @notis_ai/cli@latest -- notis apps pull ${app.targetAppId} ${JSON.stringify(app.projectDir)} --force`;
+      return `${app.name}: local version ${localVersion} is not strictly newer than installed version ${app.installedReleaseVersion}; Workspace keeps serving the online bundle. Preserve any local edits, pull latest with \`${pullCommand}\`, then bump package.json notisAppVersion before development.`;
+    });
+}
+
 async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
   const result = await runTool({
     runtime,
@@ -1305,6 +1387,7 @@ async function appsDevHandler(ctx) {
         isBundleReady: () => true,
         updateApp: () => {},
         waitForBundle: async () => {},
+        getWatcherOwnership: () => null,
       }
     : await startAppDevServer({
         apps: canonicalCandidates.map((app) => ({
@@ -1320,8 +1403,70 @@ async function appsDevHandler(ctx) {
         port,
         sessionsFilePath,
       });
+  const desktopHostOwnership = captureDesktopHostOwnership({
+    desktopOwnerId: process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_ID,
+    desktopOwnerScope: process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_SCOPE,
+  });
+
+  let heartbeatTimer = null;
+  let consumerTimer = null;
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    process.stdout.write(`\n[notis apps dev] stopping (${signal})...\n`);
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (consumerTimer) {
+      clearInterval(consumerTimer);
+      consumerTimer = null;
+    }
+    if (manualConsumerTimer) {
+      clearInterval(manualConsumerTimer);
+      manualConsumerTimer = null;
+    }
+    if (manualConsumerInstanceId) {
+      try {
+        removeAppDevConsumer(manualConsumerInstanceId);
+      } catch {
+        // A crashed CLI lease expires automatically after the heartbeat window.
+      }
+    }
+    try {
+      await devServer.close();
+    } catch {
+      // ignore cleanup failures during shutdown
+    }
+    // Keep ownership records until every watcher group has stopped. If the
+    // Desktop must force this host down, the next launch can still recover a
+    // verified orphan instead of losing its only ownership proof.
+    try {
+      removeAppDevSession(sessionId, sessionsFilePath);
+    } catch {
+      // ignore cleanup failures during shutdown
+    }
+    if (sourceHostLock) {
+      releaseAppDevHostLock(sourceHostLock);
+      sourceHostLock = null;
+    }
+    process.exit(EXIT_CODES.ok);
+  };
+  const handleSigint = () => {
+    void shutdown('SIGINT');
+  };
+  const handleSigterm = () => {
+    void shutdown('SIGTERM');
+  };
 
-  let heartbeatTimer = setInterval(() => {
+  // Electron can stop a partially registered host. Install cleanup before the
+  // first remote registration so every watcher group is still terminated when
+  // registration is slow or stuck.
+  process.on('SIGINT', handleSigint);
+  process.on('SIGTERM', handleSigterm);
+
+  heartbeatTimer = setInterval(() => {
     try {
       heartbeatAppDevSession(sessionId, new Date().toISOString(), sessionsFilePath);
     } catch (error) {
@@ -1379,6 +1524,8 @@ async function appsDevHandler(ctx) {
         sessionId,
         hostPid: process.pid,
         sourceHost: !sharedBundleBaseUrls,
+        ...(desktopHostOwnership || {}),
+        ...(devServer.getWatcherOwnership(app.devSlug) || {}),
         bundleReady: devServer.isBundleReady(app.devSlug),
         ...(!sharedBundleBaseUrls ? {
           discoveredProjects: discoveredAppDirs,
@@ -1425,6 +1572,8 @@ async function appsDevHandler(ctx) {
     }
   }
   if (apps.length === 0) {
+    process.off('SIGINT', handleSigint);
+    process.off('SIGTERM', handleSigterm);
     clearInterval(heartbeatTimer);
     heartbeatTimer = null;
     try {
@@ -1456,10 +1605,9 @@ async function appsDevHandler(ctx) {
     ...registrationWarnings,
     ...databaseMaterializationWarnings(apps),
     ...liveDataWarnings(apps),
+    ...versionPrecedenceWarnings(apps),
   ];
 
-  let consumerTimer = null;
-
   ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
@@ -1481,6 +1629,9 @@ async function appsDevHandler(ctx) {
         linked_app_id: app.linkedAppId,
         database_materialization: app.databaseMaterialization,
         live_data: app.liveData,
+        local_release_version: app.localReleaseVersion,
+        installed_release_version: app.installedReleaseVersion,
+        mount_eligible: app.mountEligible,
       })),
     },
     warnings,
@@ -1492,64 +1643,20 @@ async function appsDevHandler(ctx) {
         ? [`Databases: ${apps.filter((app) => app.liveData?.enabled).length}/${apps.length} app(s) reading the installed app's live rows`]
         : []),
       '',
-      ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
+      ...apps.map((app) => (
+        app.mountEligible
+          ? `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`
+          : `  ${app.name.padEnd(24)} online v${app.installedReleaseVersion} (local ${app.localReleaseVersion || 'version missing'})`
+      )),
       '',
       sharedBundleBaseUrls
-        ? `Mounted ${apps.length} shared source app${apps.length === 1 ? '' : 's'} for this authenticated environment.`
-        : `Serving one shared loopback host for ${apps.length} app${apps.length === 1 ? '' : 's'}.`,
+        ? `Attached to the shared source host: ${apps.filter((app) => app.mountEligible).length}/${apps.length} app${apps.length === 1 ? '' : 's'} eligible to substitute.`
+        : `Serving one shared loopback host for ${apps.length} app${apps.length === 1 ? '' : 's'}; ${apps.filter((app) => app.mountEligible).length} eligible to substitute.`,
       '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
   });
 
-  let shuttingDown = false;
-  const shutdown = async (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    process.stdout.write(`\n[notis apps dev] stopping (${signal})...\n`);
-    if (heartbeatTimer) {
-      clearInterval(heartbeatTimer);
-      heartbeatTimer = null;
-    }
-    if (consumerTimer) {
-      clearInterval(consumerTimer);
-      consumerTimer = null;
-    }
-    if (manualConsumerTimer) {
-      clearInterval(manualConsumerTimer);
-      manualConsumerTimer = null;
-    }
-    if (manualConsumerInstanceId) {
-      try {
-        removeAppDevConsumer(manualConsumerInstanceId);
-      } catch {
-        // A crashed CLI lease expires automatically after the heartbeat window.
-      }
-    }
-    try {
-      removeAppDevSession(sessionId, sessionsFilePath);
-    } catch {
-      // ignore cleanup failures during shutdown
-    }
-    try {
-      await devServer.close();
-    } catch {
-      // ignore cleanup failures during shutdown
-    }
-    if (sourceHostLock) {
-      releaseAppDevHostLock(sourceHostLock);
-      sourceHostLock = null;
-    }
-    process.exit(EXIT_CODES.ok);
-  };
-
-  process.on('SIGINT', () => {
-    void shutdown('SIGINT');
-  });
-  process.on('SIGTERM', () => {
-    void shutdown('SIGTERM');
-  });
-
   if (consumerMode === 'machine' || consumerMode === 'environment') {
     consumerTimer = setInterval(() => {
       if (!hasAppDevConsumer(readAppDevConsumers(), {
@@ -2114,8 +2221,10 @@ async function appsPullHandler(ctx) {
   const appId = ctx.args.appId;
   const result = await runToolCommand({
     runtime: ctx.runtime,
-    toolName: GET_APP_TOOL,
-    arguments_: { app_id: appId },
+    // Pull is source retrieval plus local link state. LIST_APPS is deliberately
+    // non-materializing; GET_APP hydrates missing declared databases and would
+    // turn a read-only pull into a remote mutation before build/verification.
+    toolName: LIST_APPS_TOOL,
   });
   if (
     ctx.runtime.credentialKind === 'oauth'
@@ -2123,7 +2232,11 @@ async function appsPullHandler(ctx) {
   ) {
     throw usageError('Pulling app source requires a current OAuth grant. Run `notis login` and retry.');
   }
-  const app = result.payload?.app || {};
+  const apps = Array.isArray(result.payload?.apps) ? result.payload.apps : [];
+  const app = apps.find((candidate) => (candidate?.app_id || candidate?.id) === appId);
+  if (!app) {
+    throw usageError(`App ${appId} is not accessible to the active profile.`);
+  }
   const defaultDir = slugify(app.slug) || slugify(app.name) || slugify(appId);
   const targetDir = ctx.args.dir
     ? resolveProjectDir(ctx.args.dir)
@@ -2148,7 +2261,7 @@ async function appsPullHandler(ctx) {
       project_dir: pulled.projectDir,
       version: pulled.version,
     },
-    humanSummary: `Pulled ${versionLabel} to ${pulled.projectDir}. Run \`cd ${pulled.projectDir} && npm install && notis apps dev\` to start editing.`,
+    humanSummary: `Pulled ${versionLabel} to ${pulled.projectDir}. Increment package.json notisAppVersion above the pulled release, then run \`cd ${pulled.projectDir} && npm install && notis apps dev\` to substitute the online bundle.`,
   });
 }
 
@@ -2599,7 +2712,7 @@ export const appsCommandSpecs = [
     command_path: ['apps', 'dev'],
     summary: 'Register a development root and connect its apps to the shared local development host.',
     when_to_use:
-      'Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance.',
+      'Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory or monorepo root (default: current dir).' },
@@ -2775,7 +2888,7 @@ export const appsCommandSpecs = [
     command_path: ['apps', 'pull'],
     summary: 'Download a Notis app source snapshot into a local project folder.',
     when_to_use:
-      'Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.',
+      'Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.',
     args_schema: {
       arguments: [
         { token: '<app-id>', description: 'Remote app ID to pull.' },

package/src/runtime/app-dev-process-identity.js

@@ -0,0 +1,111 @@
+import { execFileSync } from 'node:child_process';
+import { readlinkSync, realpathSync } from 'node:fs';
+
+export const NOTIS_APP_BUILD_COMMAND_FINGERPRINT = 'npm:run-build:watch:v1';
+export const NOTIS_APPS_DEV_HOST_COMMAND_FINGERPRINT = 'notis:apps-dev:v1';
+
+function normalizePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    return realpathSync(value.trim());
+  } catch {
+    return null;
+  }
+}
+
+export function isExpectedNotisBuildCommand(command) {
+  if (typeof command !== 'string') return false;
+  return /(?:^|[/\s])npm(?:\s|$)/.test(command)
+    && /\brun\s+build\b/.test(command)
+    && /(?:^|\s)--watch(?:\s|$)/.test(command);
+}
+
+export function isExpectedNotisAppsDevHostCommand(command) {
+  return typeof command === 'string'
+    && /(?:notis(?:\.js)?|@notis_ai[/\\]cli)/.test(command)
+    && /\bapps\s+dev\b/.test(command);
+}
+
+function readDarwinProcessCwd(pid, execute) {
+  const output = execute('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const line = output.split('\n').find((entry) => entry.startsWith('n'));
+  return line ? line.slice(1) : null;
+}
+
+export function inspectAppDevWatcherProcess(pid, {
+  platform = process.platform,
+  execute = execFileSync,
+  readLink = readlinkSync,
+} = {}) {
+  if (!Number.isSafeInteger(pid) || pid <= 0 || platform === 'win32') return null;
+  try {
+    const ps = (field) => execute('ps', ['-o', `${field}=`, '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const processGroupPid = Number.parseInt(ps('pgid'), 10);
+    const startIdentity = ps('lstart').replace(/\s+/g, ' ').trim();
+    const command = ps('command');
+    const cwd = platform === 'linux'
+      ? readLink(`/proc/${pid}/cwd`)
+      : readDarwinProcessCwd(pid, execute);
+    const projectDir = normalizePath(cwd);
+    if (!Number.isSafeInteger(processGroupPid) || processGroupPid <= 0) return null;
+    if (!startIdentity || !command || !projectDir) return null;
+    return { pid, processGroupPid, startIdentity, command, projectDir };
+  } catch {
+    return null;
+  }
+}
+
+export function captureDesktopWatcherOwnership({
+  pid,
+  projectDir,
+  desktopOwnerId,
+  desktopOwnerScope,
+  inspect = inspectAppDevWatcherProcess,
+} = {}) {
+  const owner = typeof desktopOwnerId === 'string' ? desktopOwnerId.trim() : '';
+  const ownerScope = typeof desktopOwnerScope === 'string' ? desktopOwnerScope.trim() : '';
+  const expectedProjectDir = normalizePath(projectDir);
+  if (!owner || !ownerScope || !expectedProjectDir) return null;
+  const identity = inspect(pid);
+  if (
+    !identity
+    || identity.processGroupPid !== pid
+    || identity.projectDir !== expectedProjectDir
+    || !isExpectedNotisBuildCommand(identity.command)
+  ) {
+    return null;
+  }
+  return {
+    desktopOwnerId: owner,
+    desktopOwnerScope: ownerScope,
+    watcherProcessGroupPid: identity.processGroupPid,
+    watcherStartIdentity: identity.startIdentity,
+    watcherProjectDir: identity.projectDir,
+    watcherCommandFingerprint: NOTIS_APP_BUILD_COMMAND_FINGERPRINT,
+  };
+}
+
+export function captureDesktopHostOwnership({
+  pid = process.pid,
+  desktopOwnerId,
+  desktopOwnerScope,
+  inspect = inspectAppDevWatcherProcess,
+} = {}) {
+  const owner = typeof desktopOwnerId === 'string' ? desktopOwnerId.trim() : '';
+  const ownerScope = typeof desktopOwnerScope === 'string' ? desktopOwnerScope.trim() : '';
+  if (!owner || !ownerScope) return null;
+  const identity = inspect(pid);
+  if (!identity || !isExpectedNotisAppsDevHostCommand(identity.command)) return null;
+  return {
+    desktopOwnerId: owner,
+    desktopOwnerScope: ownerScope,
+    desktopHostStartIdentity: identity.startIdentity,
+    desktopHostCommandFingerprint: NOTIS_APPS_DEV_HOST_COMMAND_FINGERPRINT,
+  };
+}