@notis_ai/cli 0.2.7 → 0.2.9

package/src/command-specs/apps.js

@@ -32,6 +32,7 @@ import {
   collectArtifactFiles,
   collectSourceFiles,
   resolveConfiguredAppSkills,
+  normalizeAppCapabilities,
   directDeploy,
   pullAppSource,
 } from '../runtime/app-platform.js';
@@ -43,15 +44,18 @@ import {
   runHarnessRoute,
 } from '../runtime/agent-browser.js';
 import {
+  getAppDevSessionsFile,
   heartbeatAppDevSession,
   removeAppDevSession,
   upsertAppDevSessions,
   waitForAppDevSessionMountAcknowledgements,
+  waitForAppDevSessionRenderAcknowledgements,
 } from '../runtime/app-dev-sessions.js';
 import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
 import { composeStoreScreenshot } from '../runtime/store-screenshot.js';
 import { httpRequest } from '../runtime/transport.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
 import {
   localNotisToolSlug,
   nextIdempotencyKey,
@@ -66,6 +70,7 @@ const ENSURE_DEV_APP_INSTALLATION_TOOL = 'LOCAL_NOTIS_ENSURE_DEV_APP_INSTALLATIO
 const GET_APP_TOOL = 'LOCAL_NOTIS_GET_APP';
 const LIST_APPS_TOOL = 'LOCAL_NOTIS_LIST_APPS';
 const CREATE_APP_TOOL = 'LOCAL_NOTIS_CREATE_APP';
+const DUPLICATE_APP_TOOL = 'LOCAL_NOTIS_DUPLICATE_APP';
 const SAVE_APP_FILES_TOOL = 'LOCAL_NOTIS_SAVE_APP_FILES';
 
 // ---------------------------------------------------------------------------
@@ -138,13 +143,24 @@ function decodeJwtSub(jwt) {
   }
 }
 
-function openInBrowser(url) {
-  const platform = process.platform;
+export function developmentDesktopOpenCommand(
+  url,
+  {
+    platform = process.platform,
+    appName = null,
+    bundleId = null,
+    scheme = 'notis',
+  } = {},
+) {
   let command;
   let args;
   if (platform === 'darwin') {
     command = 'open';
-    args = [url];
+    args = bundleId && scheme === 'notis'
+      ? ['-b', bundleId, url]
+      : appName && scheme === 'notis'
+        ? ['-a', appName, url]
+        : [url];
   } else if (platform === 'win32') {
     command = 'cmd';
     args = ['/c', 'start', '', url];
@@ -152,10 +168,14 @@ function openInBrowser(url) {
     command = 'xdg-open';
     args = [url];
   }
+  return { command, args };
+}
+
+function openInBrowser(url, options = {}) {
+  const { command, args } = developmentDesktopOpenCommand(url, options);
   try {
-    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    const child = spawn(command, args, { stdio: 'ignore' });
     child.on('error', () => {});
-    child.unref();
   } catch {
     // Non-fatal. The URL is printed in the CLI output.
   }
@@ -205,21 +225,55 @@ function pickDefaultRouteSlug(manifest) {
 
 const DESKTOP_DEEP_LINK_SCHEME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
-export function resolveDevelopmentDesktopScheme(env = process.env) {
+export function resolveDevelopmentDesktopScheme(env = process.env, worktreeRuntime = null) {
   // Mirror the desktop app's own scheme resolution (electron main + forge config):
   // local dev launches register `notis-dev`, while installed prod/beta builds claim
   // `notis`. Hardcoding `notis` here is what made `apps dev` open the installed
   // prod/beta app instead of the local dev app.
-  const scheme = (env.NOTIS_DESKTOP_DEEP_LINK_SCHEME || '').trim();
+  const scheme = (
+    worktreeRuntime?.desktop_deep_link_scheme
+    || env.NOTIS_DESKTOP_DEEP_LINK_SCHEME
+    || ''
+  ).trim();
   return DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
 }
 
+export function resolveDevelopmentDesktopAppName(runtime = {}) {
+  const explicit = String(
+    runtime.desktopAppName
+    || runtime.worktreeRuntime?.desktop_app_name
+    || '',
+  ).trim();
+  if (explicit) {
+    return explicit;
+  }
+  try {
+    return new URL(runtime.apiBase).hostname === 'api-beta.notis.ai'
+      ? 'Notis Beta'
+      : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function resolveDevelopmentDesktopBundleId(runtime = {}) {
+  return resolveDevelopmentDesktopAppName(runtime) === 'Notis Beta'
+    ? 'ai.notis.desktop.beta'
+    : 'ai.notis.desktop';
+}
+
 export function buildDevelopmentDesktopUrl(appHref = null, scheme = 'notis') {
   const route = String(appHref || '/store').replace(/^\/+/, '');
   const normalizedScheme = DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
   return `${normalizedScheme}://${route || 'store'}`;
 }
 
+export function buildMountedDevelopmentDesktopUrl(appHref, scheme, sessionId) {
+  const url = new URL(buildDevelopmentDesktopUrl(appHref, scheme));
+  url.searchParams.set('notis_dev_session', sessionId);
+  return url.toString();
+}
+
 export function shouldOpenDevelopmentTab(options = {}) {
   // Commander stores the negatable `--no-open` flag as `options.open === false`;
   // it never sets `options.noOpen`. Reading the non-existent `noOpen` key meant
@@ -228,8 +282,17 @@ export function shouldOpenDevelopmentTab(options = {}) {
   return options.open !== false;
 }
 
-function buildAppHref({ appSlug, appId, manifest }) {
-  const originlessBase = `/apps/${appSlug}-${appId}`;
+export function buildDevelopmentAppHref({
+  appSlug,
+  appId,
+  devSlug,
+  targetAppId = null,
+  targetAppSlug = null,
+  manifest,
+}) {
+  const routeAppId = `${targetAppId || appId}__local_dev__${devSlug}`;
+  const routeAppSlug = targetAppSlug || devSlug || appSlug;
+  const originlessBase = `/apps/${routeAppSlug}-${routeAppId}`;
   const routeSlug = pickDefaultRouteSlug(manifest);
   return routeSlug ? `${originlessBase}/${routeSlug}` : originlessBase;
 }
@@ -377,22 +440,35 @@ function assertHarnessResult(result, route, databaseSlugs) {
       details: error,
     });
   }
-  for (const databaseSlug of databaseSlugs) {
-    const seen = (result.runtimeCalls || []).some(
-      (call) =>
-        call?.op === 'callTool' &&
-        localNotisToolSlug(call?.args?.name) === 'LOCAL_NOTIS_DATABASE_QUERY' &&
-        call?.args?.arguments?.database_slug === databaseSlug,
-    );
-    if (!seen) {
+  const declaredDatabaseSet = new Set(databaseSlugs);
+  const databaseQueries = (result.runtimeCalls || []).filter(
+    (call) =>
+      call?.op === 'callTool'
+      && localNotisToolSlug(call?.args?.name) === 'LOCAL_NOTIS_DATABASE_QUERY',
+  );
+  for (const call of databaseQueries) {
+    const databaseSlug = call?.args?.arguments?.database_slug;
+    if (databaseSlug && !declaredDatabaseSet.has(databaseSlug)) {
       assertions.push({
         ok: false,
-        code: 'missing_database_query',
-        message: `Route "${route.slug}" did not call LOCAL_NOTIS_DATABASE_QUERY for "${databaseSlug}".`,
+        code: 'undeclared_database_query',
+        message: `Route "${route.slug}" queried undeclared database "${databaseSlug}".`,
         details: { databaseSlug },
       });
     }
   }
+  const collectionDatabase = route?.collection?.database;
+  if (
+    collectionDatabase
+    && !databaseQueries.some((call) => call?.args?.arguments?.database_slug === collectionDatabase)
+  ) {
+    assertions.push({
+      ok: false,
+      code: 'missing_collection_database_query',
+      message: `Collection route "${route.slug}" did not query "${collectionDatabase}".`,
+      details: { databaseSlug: collectionDatabase },
+    });
+  }
   return assertions;
 }
 
@@ -440,6 +516,7 @@ function buildManifestForDev(appConfig) {
       css: 'bundle/app.css',
     },
     databases: appConfig.databases || [],
+    capabilities: normalizeAppCapabilities(appConfig.capabilities),
     tools: appConfig.tools || [],
     skills: (appConfig.skills || []).map((skill) => ({
       key: skill.key,
@@ -483,11 +560,12 @@ export async function ensureDevInstall({
   const manifest = buildManifestForDev(appConfig);
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   let linkedState = readLinkedState(projectDir);
+  let linkedApp = null;
   if (linkedState?.app_id) {
-    const linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
-    if (!linkedApp || linkedApp.manifest?.is_dev === true) {
+    linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
+    if (linkedApp?.manifest?.is_dev === true) {
       const { app_id: legacyDevAppId, linked_at: _linkedAt, deployed_at: _deployedAt, version: _version, ...rest } = linkedState;
-      const devAppId = linkedState.dev_app_id || (linkedApp ? legacyDevAppId : null);
+      const devAppId = linkedState.dev_app_id || legacyDevAppId;
       linkedState = {
         ...rest,
         ...(devAppId ? { dev_app_id: devAppId } : {}),
@@ -496,6 +574,7 @@ export async function ensureDevInstall({
         } : {}),
       };
       writeLinkedState(projectDir, linkedState);
+      linkedApp = null;
     }
   }
   const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills });
@@ -528,6 +607,7 @@ export async function ensureDevInstall({
     created: ensureResult.payload.created || false,
     linkedAppId: linkedState?.app_id || null,
     targetAppId: linkedState?.app_id || null,
+    targetAppSlug: linkedApp?.slug || null,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
@@ -709,6 +789,15 @@ async function appsDevHandler(ctx) {
     throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
   }
   const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
+  const sessionsFilePath = getAppDevSessionsFile(
+    ctx.runtime.worktreeRuntime?.app_dev_sessions_file,
+  );
+  const desktopScheme = resolveDevelopmentDesktopScheme(
+    process.env,
+    ctx.runtime.worktreeRuntime,
+  );
+  const desktopAppName = resolveDevelopmentDesktopAppName(ctx.runtime);
+  const desktopBundleId = resolveDevelopmentDesktopBundleId(ctx.runtime);
   const sessionId = randomUUID();
 
   const candidates = [];
@@ -764,16 +853,25 @@ async function appsDevHandler(ctx) {
       ...app,
       bundleBaseUrl,
       mountNonce: randomUUID(),
-      appHref: buildAppHref({
+      appHref: buildDevelopmentAppHref({
         appSlug: app.slug,
         appId: app.appId,
+        devSlug: app.devSlug,
+        targetAppId: app.targetAppId,
+        targetAppSlug: app.targetAppSlug,
         manifest: app.manifest,
       }),
     };
   });
   const developmentTabUrl = buildDevelopmentDesktopUrl(
     apps[0]?.appHref,
-    resolveDevelopmentDesktopScheme(),
+    desktopScheme,
+  );
+  const desktopWakeUrl = buildDevelopmentDesktopUrl('/manage', desktopScheme);
+  const mountedDevelopmentTabUrl = buildMountedDevelopmentDesktopUrl(
+    apps[0]?.appHref,
+    desktopScheme,
+    sessionId,
   );
   const warnings = databaseMaterializationWarnings(apps);
 
@@ -786,6 +884,7 @@ async function appsDevHandler(ctx) {
       userId: identity,
     })),
     port,
+    sessionsFilePath,
   });
 
   try {
@@ -802,7 +901,8 @@ async function appsDevHandler(ctx) {
       projectDir: app.projectDir,
       startedAt: now,
       lastHeartbeatAt: now,
-    })));
+      desktopAppName,
+    })), sessionsFilePath);
   } catch (error) {
     try {
       await devServer.close();
@@ -814,7 +914,7 @@ async function appsDevHandler(ctx) {
 
   let heartbeatTimer = setInterval(() => {
     try {
-      heartbeatAppDevSession(sessionId, new Date().toISOString());
+      heartbeatAppDevSession(sessionId, new Date().toISOString(), sessionsFilePath);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[notis apps dev] heartbeat failed: ${message}\n`);
@@ -836,6 +936,8 @@ async function appsDevHandler(ctx) {
       development_url: developmentTabUrl,
       session_id: sessionId,
       mount_status: 'serving',
+      render_status: 'waiting_for_route',
+      desktop_target: desktopAppName,
       identity,
       apps: apps.map((app) => ({
         slug: app.devSlug,
@@ -853,36 +955,67 @@ async function appsDevHandler(ctx) {
     warnings,
     humanSummary: [
       `Running apps dev against ${apiBase} as ${identity} (mode: ${mode})`,
+      `Target desktop: ${desktopAppName}`,
       '',
       `Open in desktop: ${developmentTabUrl}`,
       '',
       ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
       '',
-      `Serving locally; waiting for Notis to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
+      `Serving locally; waiting for ${desktopAppName} to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
       '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
   });
 
   if (shouldOpenDevelopmentTab(ctx.options)) {
-    openInBrowser(developmentTabUrl);
+    openInBrowser(desktopWakeUrl, {
+      appName: desktopAppName,
+      bundleId: desktopBundleId,
+      scheme: desktopScheme,
+    });
   }
 
   void (async () => {
-    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements);
+    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+      sessionsFilePath,
+    });
     if (!result.mounted) {
       process.stderr.write(
-        `[notis apps dev] Serving locally, but Notis has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open Notis.\n`,
+        `[notis apps dev] Serving locally, but ${desktopAppName} has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open ${desktopAppName}.\n`,
       );
     }
     while (!result.mounted) {
       result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+        sessionsFilePath,
+        timeoutMs: 60_000,
+        pollIntervalMs: 250,
+      });
+    }
+    process.stderr.write(
+      `[notis apps dev] Mounted in ${desktopAppName}: ${apps.map((app) => app.name).join(', ')}.\n`,
+    );
+    if (shouldOpenDevelopmentTab(ctx.options)) {
+      openInBrowser(mountedDevelopmentTabUrl, {
+        appName: desktopAppName,
+        bundleId: desktopBundleId,
+        scheme: desktopScheme,
+      });
+    }
+
+    const firstAppRender = expectedMountAcknowledgements.slice(0, 1);
+    let renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+      sessionsFilePath,
+      timeoutMs: 0,
+    });
+    while (!renderResult.mounted) {
+      renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+        sessionsFilePath,
         timeoutMs: 60_000,
         pollIntervalMs: 250,
       });
     }
     process.stderr.write(
-      `[notis apps dev] Mounted in Notis: ${apps.map((app) => app.name).join(', ')}.\n`,
+      `[notis apps dev] Rendered in ${desktopAppName}: ${apps[0].name}.\n`,
     );
   })().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
@@ -899,7 +1032,7 @@ async function appsDevHandler(ctx) {
       heartbeatTimer = null;
     }
     try {
-      removeAppDevSession(sessionId);
+      removeAppDevSession(sessionId, sessionsFilePath);
     } catch {
       // ignore cleanup failures during shutdown
     }
@@ -930,7 +1063,9 @@ async function appsBuildHandler(ctx) {
     throw usageError(`Project has problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
   }
 
-  const { manifest } = await buildArtifact(projectDir);
+  const { manifest } = await buildArtifact(projectDir, {
+    stdio: ctx.output.isMachineMode() ? 'pipe' : 'inherit',
+  });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
@@ -953,6 +1088,12 @@ async function appsVerifyHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live verify mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live verify mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -963,7 +1104,9 @@ async function appsVerifyHandler(ctx) {
   }
 
   if (!ctx.options.skipBuild) {
-    await buildArtifact(projectDir);
+    await buildArtifact(projectDir, {
+      stdio: ctx.output.isMachineMode() ? 'pipe' : 'inherit',
+    });
   }
 
   const manifest = readManifest(projectDir);
@@ -1165,6 +1308,12 @@ async function appsScreenshotHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -1175,7 +1324,9 @@ async function appsScreenshotHandler(ctx) {
   }
 
   if (!ctx.options.skipBuild) {
-    await buildArtifact(projectDir);
+    await buildArtifact(projectDir, {
+      stdio: ctx.output.isMachineMode() ? 'pipe' : 'inherit',
+    });
   }
 
   const manifest = readManifest(projectDir);
@@ -1364,16 +1515,25 @@ async function appsScreenshotHandler(ctx) {
   }
 }
 
+export function buildLinkedAppState(existingState, appId, linkedAt = new Date().toISOString()) {
+  return {
+    ...(existingState?.dev_app_id ? { dev_app_id: existingState.dev_app_id } : {}),
+    ...(existingState?.dev_linked_at ? { dev_linked_at: existingState.dev_linked_at } : {}),
+    app_id: appId,
+    linked_at: linkedAt,
+  };
+}
+
 async function appsLinkHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const appId = ctx.args.appId;
 
   await assertLinkTarget(ctx.runtime, appId);
 
-  writeLinkedState(projectDir, {
-    app_id: appId,
-    linked_at: new Date().toISOString(),
-  });
+  writeLinkedState(
+    projectDir,
+    buildLinkedAppState(readLinkedState(projectDir), appId),
+  );
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
@@ -1392,6 +1552,12 @@ async function appsPullHandler(ctx) {
     toolName: GET_APP_TOOL,
     arguments_: { app_id: appId },
   });
+  if (
+    ctx.runtime.credentialKind === 'oauth'
+    && !await ensureFreshOAuthCredential(ctx.runtime)
+  ) {
+    throw usageError('Pulling app source requires a current OAuth grant. Run `notis login` and retry.');
+  }
   const app = result.payload?.app || {};
   const defaultDir = app.slug || slugify(app.name) || appId;
   const targetDir = resolveProjectDir(ctx.args.dir || defaultDir);
@@ -1442,7 +1608,9 @@ async function appsDeployHandler(ctx) {
 
   // Build if needed
   if (!ctx.options.skipBuild) {
-    await buildArtifact(projectDir);
+    await buildArtifact(projectDir, {
+      stdio: ctx.output.isMachineMode() ? 'pipe' : 'inherit',
+    });
   }
 
   // Direct deploy mode: upload to Supabase storage directly
@@ -1539,6 +1707,67 @@ function deployedAppVersion(app) {
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
+async function appsDuplicateHandler(ctx) {
+  const projectDir = resolveProjectDir(ctx.args.dir || '.');
+  // Either target an app explicitly, or duplicate whatever this project is
+  // linked to, so `notis apps duplicate` works from inside a project.
+  const appId = requireLinkedAppId(projectDir, ctx.options.appId);
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+
+  const copyDocuments = ctx.options.copyDocuments || 'declared';
+  if (!['declared', 'all', 'none'].includes(copyDocuments)) {
+    throw usageError("--copy-documents must be one of: declared, all, none.");
+  }
+
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: DUPLICATE_APP_TOOL,
+    arguments_: {
+      app_id: appId,
+      ...(ctx.options.name ? { name: ctx.options.name } : {}),
+      copy_documents: copyDocuments,
+    },
+    mutating: true,
+    idempotencyKey,
+  });
+
+  const payload = result.payload || {};
+  if (payload.status === 'error') {
+    throw usageError(`Could not duplicate app ${appId}: ${payload.message || 'unknown error'}`);
+  }
+
+  const duplicated = payload.app || {};
+  if (!duplicated.id) {
+    throw usageError(`Could not duplicate app ${appId}: the backend did not return an app id.`);
+  }
+
+  const data = {
+    app_id: duplicated.id,
+    name: duplicated.name,
+    slug: duplicated.slug,
+    duplicated_from_app_id: payload.duplicated_from_app_id || appId,
+    copied_document_count: payload.copied_document_count ?? 0,
+    portal_url: payload.portal_url,
+    idempotency_key: idempotencyKey,
+    // The duplicate owns brand new databases; nothing is shared with the source.
+    databases: (payload.databases || []).map((database) => ({
+      id: database.id,
+      slug: database.slug,
+      name: database.name,
+    })),
+  };
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data,
+    humanSummary: `Duplicated app ${appId} as ${duplicated.name || duplicated.id}`,
+    hints: payload.portal_url
+      ? [{ command: payload.portal_url, reason: 'Open the duplicated app in Portal' }]
+      : [],
+    meta: { mutating: true, idempotency_key: idempotencyKey },
+  });
+}
+
 async function appsPublishHandler(ctx) {
   if (ctx.options.confirmReady !== true) {
     throw usageError(
@@ -1652,10 +1881,20 @@ async function appsDoctorHandler(ctx) {
       ? `Found ${problems.length} problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`
       : warnings.length
         ? `Healthy with ${warnings.length} warnings:\n${warnings.map((w) => `  - ${w}`).join('\n')}`
-        : `Project is healthy.${linkedState ? ` Linked to ${linkedState.app_id}.` : ' Not linked.'}`,
+        : `Project is healthy.${doctorLinkSummary(linkedState)}`,
   });
 }
 
+export function doctorLinkSummary(linkedState) {
+  if (linkedState?.app_id) {
+    return ` Linked to app ${linkedState.app_id}.`;
+  }
+  if (linkedState?.dev_app_id) {
+    return ` Local development app ${linkedState.dev_app_id} is active.`;
+  }
+  return ' Not linked.';
+}
+
 // ---------------------------------------------------------------------------
 // Command specs
 // ---------------------------------------------------------------------------
@@ -1919,6 +2158,35 @@ export const appsCommandSpecs = [
     backend_call: { type: 'http', name: 'portal_apps/publish' },
     handler: appsPublishHandler,
   },
+  {
+    command_path: ['apps', 'duplicate'],
+    summary: 'Duplicate an app into an independent copy with its own databases.',
+    when_to_use:
+      'When the same app should run for a second purpose - a notes app for blog drafts alongside one for bookmarks. The copy shares no data with the source.',
+    args_schema: {
+      arguments: [
+        { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
+      ],
+      options: [
+        { flags: '--app-id <id>', description: 'App to duplicate. Defaults to the app this project is linked to.' },
+        { flags: '--name <name>', description: 'Name for the duplicate (default: the source name followed by "copy").' },
+        {
+          flags: '--copy-documents <mode>',
+          description:
+            "Which rows to copy: 'declared' (default, the starter content a fresh install would have), 'all', or 'none'.",
+        },
+      ],
+    },
+    examples: [
+      'notis apps duplicate --name "Blog"',
+      'notis apps duplicate --app-id abc123 --name "Bookmarks" --copy-documents none',
+    ],
+    mutates: true,
+    idempotent: false,
+    require_auth: true,
+    backend_call: { type: 'tool', name: DUPLICATE_APP_TOOL },
+    handler: appsDuplicateHandler,
+  },
   {
     command_path: ['apps', 'doctor'],
     summary: 'Check project health and readiness.',