@notis_ai/cli 0.2.0-beta.139.1 → 0.2.0-beta.144.1

package/src/command-specs/auth.js

@@ -4,10 +4,11 @@ import { installLocalAgentContext } from './agents.js';
 async function loginHandler(ctx) {
   const result = await loginWithOAuth(ctx.runtime, ctx.options, ctx.output);
   if (result.agentAuthorization) {
+    const presentation = loginAgentAuthorizationPresentation(result.agentAuthorization);
     return ctx.output.emitSuccess({
       command: 'login',
       data: result.agentAuthorization,
-      humanSummary: 'Open the authorization URL in a browser to continue.',
+      ...presentation,
     });
   }
   let agentSetup = [];
@@ -44,6 +45,27 @@ async function loginHandler(ctx) {
   });
 }
 
+export function loginAgentAuthorizationPresentation(authorization) {
+  const browserHandOff = authorization?.hand_off === 'browser_callback';
+  const nextCommand = browserHandOff
+    ? authorization?.confirm_command
+    : authorization?.redeem_command;
+  return {
+    humanSummary: browserHandOff
+      ? 'Give the user the authorization URL. Signing in there completes it — there is no code to ask them for.'
+      : 'Give the user the authorization URL, then ask them for the code it shows.',
+    hints: nextCommand
+      ? [{
+        command: nextCommand,
+        reason: browserHandOff
+          ? 'Confirm the account once they have finished in the browser'
+          : 'Redeem the code shown in the browser',
+      }]
+      : [],
+    renderHuman: () => `Authorize Notis CLI: ${authorization.authorize_url}`,
+  };
+}
+
 async function logoutHandler(ctx) {
   const result = await logoutOAuth(ctx.runtime, {
     allProfiles: Boolean(ctx.options.allProfiles),
@@ -54,12 +76,24 @@ async function logoutHandler(ctx) {
       oauth_connected: false,
       cleared_profiles: result.profiles,
     },
-    humanSummary: ctx.options.allProfiles
-      ? 'OAuth credentials were removed from all CLI profiles.'
-      : `OAuth credentials were removed from profile "${ctx.runtime.profileName}".`,
+    humanSummary: logoutHumanSummary(result, {
+      allProfiles: Boolean(ctx.options.allProfiles),
+      profileName: ctx.runtime.profileName,
+    }),
   });
 }
 
+export function logoutHumanSummary(result, { allProfiles, profileName }) {
+  if (allProfiles) {
+    return result.profiles.length > 0
+      ? 'OAuth state was cleared from all connected or pending CLI profiles.'
+      : 'No OAuth credentials were connected in any CLI profile.';
+  }
+  return result.profiles.includes(profileName)
+    ? `OAuth state was cleared for profile "${profileName}", including any pending authorization.`
+    : `No OAuth credential was connected for profile "${profileName}".`;
+}
+
 export const authCommandSpecs = [
   {
     command_path: ['login'],
@@ -71,8 +105,9 @@ export const authCommandSpecs = [
       options: [
         { flags: '--no-browser', description: 'Print the authorization URL without opening a browser.' },
         { flags: '--print-url', description: 'Print the authorization URL even when opening a browser.' },
-        { flags: '--paste-code', description: 'Use the copy-paste callback for SSH and headless machines.' },
-        { flags: '--timeout-seconds <n>', description: 'How long to wait for authorization (default 300).' },
+        { flags: '--mode <mode>', description: 'auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.' },
+        { flags: '--paste-code', description: 'Alias for --mode code.' },
+        { flags: '--timeout-seconds <n>', description: 'Authorization lifetime in seconds (default 300 while waiting in a terminal; 1800 for detached or code hand-offs).' },
         { flags: '--scope <scope>', description: 'OAuth permission to request (repeatable).', collect: true },
         { flags: '--code <code>', description: 'Redeem the code shown in the browser after a non-interactive login.' },
       ],
@@ -82,11 +117,12 @@ export const authCommandSpecs = [
       'notis login --profile work',
       'notis login --profile beta --api-base https://api-beta.notis.ai',
       'notis login --no-browser --print-url',
-      'notis login --paste-code',
+      'notis login --mode browser',
+      'notis login --mode code',
       'notis login --code 4f3c2b1a',
     ],
     output_schema:
-      'Returns credential_source, profile, api_base, user_id, scopes, and credential expiries; agent mode returns authorize_url and expires_in.',
+      'Returns credential_source, profile, api_base, user_id, scopes, and credential expiries; non-blocking agent, machine-output, or non-interactive modes return authorize_url, expires_in, and hand_off ("browser_callback" needs no code, "code" must be redeemed with redeem_command).',
     mutates: true,
     idempotent: true,
     require_auth: false,
@@ -103,14 +139,15 @@ export const authCommandSpecs = [
     args_schema: {
       arguments: [],
       options: [
-        { flags: '--all-profiles', description: 'Remove OAuth credentials from every CLI profile.' },
+        { flags: '--all-profiles', description: 'Clear OAuth credentials and pending authorizations from every CLI profile.' },
       ],
     },
     examples: ['notis logout', 'notis logout --profile work', 'notis logout --all-profiles'],
-    output_schema: 'Returns oauth_connected=false and the profiles whose OAuth credentials were removed.',
+    output_schema: 'Returns oauth_connected=false and the profiles whose OAuth credentials or pending authorizations were cleared.',
     mutates: true,
     idempotent: true,
     require_auth: false,
+    allow_unknown_profile: true,
     related_commands: ['notis login', 'notis profile list'],
     backend_call: { type: 'oauth', name: 'revocation' },
     handler: logoutHandler,

package/src/command-specs/onboarding.js

@@ -11,6 +11,7 @@ import {
 } from '../runtime/profiles.js';
 import { ensureFreshOAuthCredential, loginWithOAuth } from '../runtime/oauth.js';
 import { runToolCommand } from './helpers.js';
+import { loginAgentAuthorizationPresentation } from './auth.js';
 import { installLocalAgentContext } from './agents.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -223,8 +224,13 @@ async function startHandler(ctx) {
   // Browser authorization is the whole signup path: it creates the account when
   // the address is new and authorizes this machine either way. There is nothing
   // for the CLI to collect up front, and nothing to wait on afterwards.
-  const authorization = await loginWithOAuth(runtime, { browser: true }, output);
+  const authorization = await loginWithOAuth(
+    runtime,
+    { browser: true, mode: options.mode, reusePersistedCredential: true },
+    output,
+  );
   if (authorization?.agentAuthorization) {
+    const presentation = loginAgentAuthorizationPresentation(authorization.agentAuthorization);
     return output.emitSuccess({
       command: 'start',
       data: {
@@ -232,8 +238,7 @@ async function startHandler(ctx) {
         profile: runtime.profileName,
         ...authorization.agentAuthorization,
       },
-      humanSummary: 'Open the authorization URL to create or access the Notis account.',
-      renderHuman: () => `Authorize Notis CLI: ${authorization.agentAuthorization.authorize_url}`,
+      ...presentation,
     });
   }
 
@@ -262,16 +267,18 @@ export const onboardingCommandSpecs = [
       arguments: [],
       options: [
         { flags: '--brief-only', description: 'Print the onboarding brief for an already-signed-in profile.' },
+        { flags: '--mode <mode>', description: 'auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.' },
       ],
     },
     examples: [
       'notis start',
       'notis start --profile work',
+      'notis start --mode browser',
       'notis start --brief-only',
       'notis start --json',
     ],
     output_schema:
-      'Returns {authenticated, profile, api_base, onboarding_complete, known_settings, missing_settings, agent_setup, brief, brief_source} once signed in — brief is null when onboarding_complete is true — or {authorize_url, expires_in, redeem_command} while waiting for browser authorization.',
+      'Returns {authenticated, profile, api_base, onboarding_complete, known_settings, missing_settings, agent_setup, brief, brief_source} once signed in — brief is null when onboarding_complete is true — or {authorize_url, expires_in, hand_off, ...} while waiting for browser authorization. hand_off is "browser_callback" when signing in finishes the login by itself (re-run confirm_command to see it land) or "code" when the user must be asked for the code the page shows and it redeemed with redeem_command.',
     mutates: true,
     idempotent: true,
     require_auth: false,

package/src/runtime/app-dev-consumers.js

@@ -0,0 +1,154 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_APP_DEV_CONSUMERS_FILE = join(homedir(), '.notis', 'app-dev-consumers.json');
+export const APP_DEV_CONSUMER_EXPIRES_AFTER_MS = 10_000;
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+const CONSUMER_LOCK_STALE_AFTER_MS = 30_000;
+
+function processIsRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+function reclaimConsumerLock(lockPath) {
+  const stat = lstatSync(lockPath);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Refusing unsafe app development consumer lock: ${lockPath}`);
+  }
+  let ownerPid = null;
+  try {
+    const owner = readFileSync(join(lockPath, 'owner'), 'utf8').trim();
+    const parsed = Number.parseInt(owner.split('.')[0] || '', 10);
+    ownerPid = Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    // An interrupted owner write is reclaimed after the bounded stale window.
+  }
+  if (ownerPid !== null) return !processIsRunning(ownerPid);
+  return Date.now() - stat.mtimeMs >= CONSUMER_LOCK_STALE_AFTER_MS;
+}
+
+function withLock(filePath, callback) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const lockPath = `${filePath}.lock`;
+  const owner = `${process.pid}.${randomUUID()}`;
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      writeFileSync(join(lockPath, 'owner'), owner, { mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (reclaimConsumerLock(lockPath)) {
+          rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (lockError) {
+        if (lockError?.code === 'ENOENT') continue;
+        throw lockError;
+      }
+      if (Date.now() - startedAt > 2_000) {
+        throw new Error('App development consumer registry is busy.');
+      }
+      Atomics.wait(waitArray, 0, 0, 10);
+    }
+  }
+  try {
+    return callback();
+  } finally {
+    try {
+      if (readFileSync(join(lockPath, 'owner'), 'utf8').trim() === owner) {
+        rmSync(lockPath, { recursive: true, force: true });
+      }
+    } catch {
+      // A replaced lock belongs to another writer.
+    }
+  }
+}
+
+function normalize(value, now) {
+  const raw = value && typeof value === 'object' && Array.isArray(value.consumers)
+    ? value.consumers
+    : [];
+  return raw.filter((lease) => {
+    const heartbeat = Date.parse(String(lease?.lastHeartbeatAt || ''));
+    return typeof lease?.instanceId === 'string'
+      && typeof lease?.userId === 'string'
+      && typeof lease?.apiBase === 'string'
+      && Number.isSafeInteger(lease?.pid)
+      && Number.isFinite(heartbeat)
+      && now - heartbeat <= APP_DEV_CONSUMER_EXPIRES_AFTER_MS;
+  });
+}
+
+export function readAppDevConsumers(filePath = DEFAULT_APP_DEV_CONSUMERS_FILE, now = Date.now()) {
+  if (!existsSync(filePath)) return [];
+  try {
+    return normalize(JSON.parse(readFileSync(filePath, 'utf8')), now);
+  } catch {
+    return [];
+  }
+}
+
+function writeAppDevConsumers(filePath, consumers) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporary = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, JSON.stringify({ version: 1, consumers }, null, 2), { mode: 0o600 });
+  renameSync(temporary, filePath);
+}
+
+export function heartbeatAppDevConsumer(
+  lease,
+  filePath = DEFAULT_APP_DEV_CONSUMERS_FILE,
+) {
+  return withLock(filePath, () => {
+    const now = Date.now();
+    const next = readAppDevConsumers(filePath, now)
+      .filter((entry) => entry.instanceId !== lease.instanceId);
+    next.push({
+      ...lease,
+      apiBase: lease.apiBase.replace(/\/$/, ''),
+      lastHeartbeatAt: new Date(now).toISOString(),
+    });
+    writeAppDevConsumers(filePath, next);
+    return next;
+  });
+}
+
+export function removeAppDevConsumer(
+  instanceId,
+  filePath = DEFAULT_APP_DEV_CONSUMERS_FILE,
+) {
+  return withLock(filePath, () => {
+    const next = readAppDevConsumers(filePath)
+      .filter((entry) => entry.instanceId !== instanceId);
+    writeAppDevConsumers(filePath, next);
+    return next;
+  });
+}
+
+export function hasAppDevConsumer(consumers, { mode, userId, apiBase }) {
+  if (mode === 'machine') return consumers.length > 0;
+  if (mode !== 'environment') return true;
+  const normalizedApiBase = String(apiBase || '').replace(/\/$/, '');
+  return consumers.some((consumer) => (
+    consumer.userId === userId
+    && consumer.apiBase.replace(/\/$/, '') === normalizedApiBase
+  ));
+}

package/src/runtime/app-dev-host-lock.js

@@ -0,0 +1,80 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DEFAULT_LOCK_ROOT = join(homedir(), '.notis', 'app-dev-host-locks');
+const OWNER_FILE = 'owner.json';
+
+function processIsRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+function lockName(identity, apiBase, projectDir) {
+  return createHash('sha256').update(`${identity}\0${apiBase}\0${projectDir}`).digest('hex');
+}
+
+function readOwner(path) {
+  try {
+    const value = JSON.parse(readFileSync(join(path, OWNER_FILE), 'utf8'));
+    return Number.isSafeInteger(value?.pid) && typeof value?.ownerId === 'string'
+      ? { pid: value.pid, ownerId: value.ownerId }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function reclaimable(path, now, staleAfterMs) {
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Refusing unsafe app development host lock: ${path}`);
+  }
+  const owner = readOwner(path);
+  if (owner) return !processIsRunning(owner.pid);
+  return now - stat.mtimeMs >= staleAfterMs;
+}
+
+export function tryAcquireAppDevHostLock(options) {
+  const lockRoot = options.lockRoot || DEFAULT_LOCK_ROOT;
+  mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+  const path = join(lockRoot, lockName(options.identity, options.apiBase, options.projectDir));
+  const ownerId = `${process.pid}.${randomUUID()}`;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      try {
+        writeFileSync(join(path, OWNER_FILE), JSON.stringify({ pid: process.pid, ownerId }), {
+          mode: 0o600,
+        });
+      } catch (error) {
+        rmSync(path, { recursive: true, force: true });
+        throw error;
+      }
+      return { path, ownerId };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      if (reclaimable(path, options.now ?? Date.now(), options.staleAfterMs ?? 60_000)) {
+        rmSync(path, { recursive: true, force: true });
+        continue;
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
+export function releaseAppDevHostLock(lock) {
+  try {
+    if (readOwner(lock.path)?.ownerId === lock.ownerId) {
+      rmSync(lock.path, { recursive: true, force: true });
+    }
+  } catch {
+    // A replaced lock belongs to another process.
+  }
+}

package/src/runtime/app-dev-roots.js

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, parse as parsePath, resolve } from 'node:path';
+
+import { usageError } from './errors.js';
+import { CONFIG_DIR } from './profiles.js';
+
+export const APP_DEV_ROOTS_VERSION = 1;
+export const DEFAULT_APP_DEV_ROOT = join(homedir(), '.notis', 'apps');
+export const DEFAULT_APP_DEV_ROOTS_FILE = join(CONFIG_DIR, 'app-dev-roots.json');
+const CONFIG_FILENAMES = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'];
+const LOCK_TIMEOUT_MS = 5_000;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+
+function rootsFile(filePath) {
+  if (filePath) return resolve(filePath);
+  const envPath = process.env.NOTIS_APP_DEV_ROOTS_FILE;
+  return typeof envPath === 'string' && envPath.trim()
+    ? resolve(envPath.trim())
+    : DEFAULT_APP_DEV_ROOTS_FILE;
+}
+
+function legacyProjectsFile(filePath) {
+  const sessionsFile = filePath
+    || join(CONFIG_DIR, 'app-dev-sessions.json');
+  const parsed = parsePath(resolve(sessionsFile));
+  return join(parsed.dir, `${parsed.name}-projects${parsed.ext || '.json'}`);
+}
+
+function readLockOwner(lockPath) {
+  try {
+    return readFileSync(join(lockPath, 'owner'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function withLock(filePath, callback) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const lockPath = `${filePath}.lock`;
+  const owner = `${process.pid}.${randomUUID()}`;
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      writeFileSync(join(lockPath, 'owner'), owner, { mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        const stat = lstatSync(lockPath);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+          throw new Error(`Refusing unsafe app development roots lock: ${lockPath}`);
+        }
+        const existingOwner = readLockOwner(lockPath);
+        const pid = Number.parseInt(String(existingOwner || '').split('.')[0] || '', 10);
+        if (Number.isInteger(pid) && pid > 0) {
+          try {
+            process.kill(pid, 0);
+          } catch (ownerError) {
+            if (ownerError?.code === 'ESRCH') {
+              rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            }
+          }
+        }
+      } catch (statError) {
+        if (statError?.code === 'ENOENT') continue;
+        throw statError;
+      }
+      if (Date.now() - startedAt >= LOCK_TIMEOUT_MS) {
+        throw new Error(`Timed out waiting for app development roots lock: ${filePath}`);
+      }
+      Atomics.wait(lockWait, 0, 0, 10);
+    }
+  }
+  try {
+    return callback();
+  } finally {
+    if (readLockOwner(lockPath) === owner) {
+      rmSync(lockPath, { recursive: true, force: true });
+    }
+  }
+}
+
+function canonicalExistingDirectory(inputPath) {
+  const absolute = resolve(String(inputPath || ''));
+  let stat;
+  try {
+    stat = statSync(absolute);
+  } catch {
+    throw usageError(`App development root does not exist: ${absolute}`);
+  }
+  if (!stat.isDirectory()) {
+    throw usageError(`App development root is not a directory: ${absolute}`);
+  }
+  return realpathSync(absolute);
+}
+
+function normalizeRegistry(raw) {
+  const roots = Array.isArray(raw?.roots) ? raw.roots : [];
+  const seen = new Set();
+  return roots
+    .map((entry) => typeof entry === 'string' ? { path: entry } : entry)
+    .filter((entry) => entry && typeof entry.path === 'string' && entry.path.trim())
+    .map((entry) => ({
+      path: resolve(entry.path),
+      registeredAt: typeof entry.registeredAt === 'string'
+        ? entry.registeredAt
+        : new Date(0).toISOString(),
+    }))
+    .filter((entry) => {
+      if (seen.has(entry.path)) return false;
+      seen.add(entry.path);
+      return true;
+    });
+}
+
+function readRaw(filePath) {
+  if (!existsSync(filePath)) return { version: APP_DEV_ROOTS_VERSION, roots: [] };
+  try {
+    return {
+      version: APP_DEV_ROOTS_VERSION,
+      roots: normalizeRegistry(JSON.parse(readFileSync(filePath, 'utf8'))),
+    };
+  } catch {
+    return { version: APP_DEV_ROOTS_VERSION, roots: [] };
+  }
+}
+
+function writeRaw(registry, filePath) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const normalized = {
+    version: APP_DEV_ROOTS_VERSION,
+    roots: normalizeRegistry(registry),
+  };
+  const temporary = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, JSON.stringify(normalized, null, 2), { mode: 0o600 });
+  renameSync(temporary, filePath);
+  return normalized;
+}
+
+function migrateLegacyProjectsUnlocked(registry, options) {
+  const path = legacyProjectsFile(options.legacySessionsFilePath);
+  if (!existsSync(path)) return registry;
+  let projects = [];
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    projects = Array.isArray(raw?.projects) ? raw.projects : [];
+  } catch {
+    return registry;
+  }
+  const byPath = new Map(registry.roots.map((entry) => [entry.path, entry]));
+  for (const project of projects) {
+    if (typeof project?.projectDir !== 'string' || !project.projectDir.trim()) continue;
+    try {
+      const path = canonicalExistingDirectory(project.projectDir);
+      if (path === realpathIfExists(DEFAULT_APP_DEV_ROOT)) continue;
+      if (!byPath.has(path)) {
+        byPath.set(path, {
+          path,
+          registeredAt: typeof project.lastMountedAt === 'string'
+            ? project.lastMountedAt
+            : new Date().toISOString(),
+        });
+      }
+    } catch {
+      // Deleted or inaccessible legacy projects are intentionally not migrated.
+    }
+  }
+  rmSync(path, { force: true });
+  return { version: APP_DEV_ROOTS_VERSION, roots: [...byPath.values()] };
+}
+
+function realpathIfExists(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+export function readAppDevRoots(options = {}) {
+  const filePath = rootsFile(options.filePath);
+  let registry = readRaw(filePath);
+  if (options.migrateLegacy !== false) {
+    registry = withLock(filePath, () => {
+      const before = readRaw(filePath);
+      const after = migrateLegacyProjectsUnlocked(before, options);
+      const changed = JSON.stringify(before.roots) !== JSON.stringify(after.roots);
+      return changed ? writeRaw(after, filePath) : before;
+    });
+  }
+  const implicit = realpathIfExists(options.defaultRoot || DEFAULT_APP_DEV_ROOT);
+  const roots = [
+    { path: implicit, registeredAt: null, implicit: true },
+    ...registry.roots
+      .filter((entry) => entry.path !== implicit)
+      .map((entry) => ({ ...entry, implicit: false })),
+  ];
+  return { version: APP_DEV_ROOTS_VERSION, roots };
+}
+
+export function registerAppDevRoot(inputPath, options = {}) {
+  const path = canonicalExistingDirectory(inputPath);
+  const implicit = realpathIfExists(options.defaultRoot || DEFAULT_APP_DEV_ROOT);
+  if (path === implicit) return readAppDevRoots(options);
+  const filePath = rootsFile(options.filePath);
+  withLock(filePath, () => {
+    const registry = readRaw(filePath);
+    if (!registry.roots.some((entry) => entry.path === path)) {
+      registry.roots.push({ path, registeredAt: new Date().toISOString() });
+      writeRaw(registry, filePath);
+    }
+  });
+  return readAppDevRoots({ ...options, migrateLegacy: false });
+}
+
+export function removeAppDevRoot(inputPath, options = {}) {
+  const path = realpathIfExists(resolve(String(inputPath || '')));
+  const implicit = realpathIfExists(options.defaultRoot || DEFAULT_APP_DEV_ROOT);
+  if (path === implicit) {
+    throw usageError(`The default app development root cannot be removed: ${implicit}`);
+  }
+  const filePath = rootsFile(options.filePath);
+  let removed = false;
+  withLock(filePath, () => {
+    const registry = readRaw(filePath);
+    const next = registry.roots.filter((entry) => entry.path !== path);
+    removed = next.length !== registry.roots.length;
+    if (removed) writeRaw({ ...registry, roots: next }, filePath);
+  });
+  return { removed, path, registry: readAppDevRoots({ ...options, migrateLegacy: false }) };
+}
+
+function hasConfig(path) {
+  return CONFIG_FILENAMES.some((name) => existsSync(join(path, name)));
+}
+
+function childAppDirs(parent) {
+  if (!existsSync(parent)) return [];
+  let entries = [];
+  try {
+    entries = readdirSync(parent, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => !entry.name.startsWith('.') && !entry.name.startsWith('_'))
+    .filter((entry) => entry.name !== 'node_modules')
+    .map((entry) => join(parent, entry.name))
+    .filter(hasConfig);
+}
+
+export function discoverAppProjectsInRoot(inputRoot) {
+  const root = realpathIfExists(resolve(inputRoot));
+  const candidates = [];
+  if (hasConfig(root)) candidates.push(root);
+  candidates.push(...childAppDirs(root));
+  candidates.push(...childAppDirs(join(root, 'apps')));
+  return [...new Set(candidates.map(realpathIfExists))].sort();
+}
+
+export function discoverRegisteredAppProjects(options = {}) {
+  const roots = readAppDevRoots(options).roots;
+  return [...new Set(roots.flatMap((entry) => discoverAppProjectsInRoot(entry.path)))].sort();
+}
+
+export function getAppDevRootsFile(filePath) {
+  return rootsFile(filePath);
+}