@portel/photon 1.7.0 → 1.8.0

package/dist/cli.js

@@ -24,9 +24,9 @@ import { toEnvVarName } from './shared/config-docs.js';
 import { runTask } from './shared/task-runner.js';
 import { normalizeLogLevel, logger } from './shared/logger.js';
 import { printHeader, printInfo, printWarning, printError, printSuccess } from './cli-formatter.js';
-import { handleError, getErrorMessage, ExitCode, exitWithError, } from './shared/error-handler.js';
+import { handleError, getErrorMessage, ExitCode, exitWithError, isNodeError, } from './shared/error-handler.js';
 import { validateOrThrow, inRange, isPositive, isInteger } from './shared/validation.js';
-import { createReadline, promptWait } from './shared/cli-utils.js';
+import { createReadline, promptText, promptWait } from './shared/cli-utils.js';
 import { registerMarketplaceCommands } from './cli/commands/marketplace.js';
 import { registerInfoCommand } from './cli/commands/info.js';
 import { registerPackageCommands } from './cli/commands/package.js';
@@ -259,7 +259,10 @@ async function handleUrlElicitation(ask) {
         execFile(openCommand, [ask.url]);
     }
     catch (error) {
-        cliHint('Please open the URL manually in your browser.');
+        const msg = isNodeError(error, 'ENOENT')
+            ? `Could not find '${openCommand}' to open URLs`
+            : getErrorMessage(error);
+        cliHint(`Could not open browser: ${msg}. Please open the URL manually.`);
     }
     const shouldContinue = await promptWait('Press Enter when done', true);
     return { action: shouldContinue ? 'accept' : 'cancel' };
@@ -758,6 +761,9 @@ program
     .configureHelp({
     sortSubcommands: false,
     sortOptions: false,
+    // Hide Commander's auto-generated "Commands:" section since we show
+    // a custom categorized section in addHelpText('after', ...)
+    visibleCommands: () => [],
 })
     .addHelpText('after', `
 Runtime Commands:
@@ -767,6 +773,11 @@ Runtime Commands:
   beam                    Launch Photon Beam (interactive control panel)
   serve                   Start local multi-tenant MCP hosting for development
 
+Configuration:
+  use <photon> [instance]  Switch to a named instance of a stateful photon
+  instances <photon>       List all instances of a stateful photon
+  set <photon> [values]    Configure environment for a photon
+
 Hosting:
   host <command>          Manage cloud hosting (preview, deploy)
 
@@ -1113,8 +1124,12 @@ program
                     logger.debug(`Could not auto-open browser: ${err.message}`);
             });
         }
-        // Handle shutdown signals
+        // Handle shutdown signals (guard against duplicate Ctrl+C)
+        let shuttingDown = false;
         const shutdown = async () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
             console.error('\nShutting down Photon Beam...');
             // Gracefully close external MCP clients to prevent ugly tracebacks
             try {
@@ -1363,11 +1378,15 @@ maker
         // Check if file already exists
         try {
             await fs.access(filePath);
-            logger.error(`File already exists: ${filePath}`);
-            process.exit(1);
+            exitWithError(`File already exists: ${filePath}`, {
+                suggestion: `Choose a different name or delete the existing file`,
+            });
         }
-        catch {
-            // File doesn't exist, good
+        catch (err) {
+            if (!isNodeError(err, 'ENOENT')) {
+                exitWithError(`Cannot access ${filePath}: ${getErrorMessage(err)}`);
+            }
+            // ENOENT = file doesn't exist — good, proceed
         }
         // Read template
         const templatePath = path.join(__dirname, '..', 'templates', 'photon.template.ts');
@@ -1375,8 +1394,8 @@ maker
         try {
             template = await fs.readFile(templatePath, 'utf-8');
         }
-        catch {
-            // Fallback inline template if file not found
+        catch (err) {
+            logger.debug(`Template not found at ${templatePath}, using inline template`);
             template = getInlineTemplate();
         }
         // Replace placeholders
@@ -1824,6 +1843,590 @@ SEE ALSO:
         await runMethod(photon, method, args);
     }
 });
+// Use command: switch to a named instance of a stateful photon
+program
+    .command('use')
+    .argument('<photon>', 'Photon name')
+    .argument('[instance]', 'Instance name (omit for default)')
+    .description('Switch to a named instance of a stateful photon')
+    .action(async (photonName, instance) => {
+    try {
+        const { CLISessionStore } = await import('./context-store.js');
+        // Write to CLI session store only — each client manages its own instance
+        new CLISessionStore().setCurrentInstance(photonName, instance || '');
+        const label = instance || 'default';
+        printSuccess(`${photonName} → instance: ${label}`);
+        // Refresh completions cache (picks up new instance)
+        try {
+            const { generateCompletionCache } = await import('./shell-completions.js');
+            await generateCompletionCache();
+        }
+        catch {
+            // Best-effort: don't break the use command if cache refresh fails
+        }
+    }
+    catch (error) {
+        printError(getErrorMessage(error));
+        process.exit(1);
+    }
+});
+// Instances command: list all instances of a stateful photon
+program
+    .command('instances')
+    .argument('<photon>', 'Photon name')
+    .description('List all instances of a stateful photon')
+    .action(async (photonName) => {
+    try {
+        const { InstanceStore } = await import('./context-store.js');
+        const store = new InstanceStore();
+        const instances = store.listInstances(photonName);
+        const current = store.getCurrentInstance(photonName) || 'default';
+        if (instances.length === 0) {
+            printInfo(`No instances found for ${photonName}.`);
+            return;
+        }
+        cliHeading(`${photonName} — Instances`);
+        cliSpacer();
+        for (const name of instances) {
+            const marker = name === current ? ' ← current' : '';
+            console.log(`  ${name}${marker}`);
+        }
+        cliSpacer();
+    }
+    catch (error) {
+        printError(getErrorMessage(error));
+        process.exit(1);
+    }
+});
+// Shell command group: shell integration utilities
+const shell = program.command('shell').description('Shell integration utilities');
+shell
+    .command('init')
+    .option('--hook', 'Output the shell hook script (used internally by eval/Invoke-Expression)')
+    .description('Set up shell integration for direct photon commands and tab completion')
+    .action(async (options) => {
+    // Detect shell type
+    const userShell = process.env.SHELL || '';
+    const isPowerShell = !!process.env.PSModulePath;
+    const isZsh = !isPowerShell && userShell.includes('zsh');
+    const isBash = !isPowerShell && userShell.includes('bash');
+    let shellType = 'unsupported';
+    if (isZsh)
+        shellType = 'zsh';
+    else if (isBash)
+        shellType = 'bash';
+    else if (isPowerShell || process.platform === 'win32')
+        shellType = 'powershell';
+    // Unsupported shell — show supported list and exit
+    if (shellType === 'unsupported') {
+        const detected = userShell ? path.basename(userShell) : 'unknown';
+        printError(`Unsupported shell: ${detected}`);
+        console.log('');
+        console.log('  Supported shells:');
+        console.log('    zsh         ~/.zshrc           (macOS default)');
+        console.log('    bash        ~/.bashrc          (Linux default)');
+        console.log('    PowerShell  $PROFILE           (Windows default, cross-platform)');
+        console.log('');
+        console.log('  To use a specific shell, set $SHELL and retry:');
+        console.log('    SHELL=/bin/zsh photon shell init');
+        process.exit(1);
+    }
+    // RC file and eval/invoke line per shell
+    let rcFile;
+    let evalLine;
+    const marker = '# photon shell integration';
+    if (shellType === 'powershell') {
+        // PowerShell profile path: cross-platform
+        rcFile =
+            process.platform === 'win32'
+                ? path.join(os.homedir(), 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1')
+                : path.join(os.homedir(), '.config', 'powershell', 'Microsoft.PowerShell_profile.ps1');
+        evalLine = 'Invoke-Expression (& photon shell init --hook)';
+    }
+    else {
+        rcFile = isZsh ? path.join(os.homedir(), '.zshrc') : path.join(os.homedir(), '.bashrc');
+        evalLine = 'eval "$(photon shell init --hook)"';
+    }
+    // --hook flag: output the hook script
+    if (options.hook) {
+        const photonDir = path.join(os.homedir(), '.photon');
+        let photonNames = [];
+        try {
+            const entries = await fs.readdir(photonDir);
+            photonNames = entries
+                .filter((e) => /\.photon\.(ts|js)$/.test(e))
+                .map((e) => e.replace(/\.photon\.(ts|js)$/, ''));
+        }
+        catch {
+            // ~/.photon/ doesn't exist yet
+        }
+        if (shellType === 'zsh') {
+            const functions = photonNames
+                .map((name) => `${name}() { photon cli ${name} "$@"; }`)
+                .join('\n');
+            console.log(`${marker}
+
+# Shell functions for installed photons (direct invocation)
+${functions}
+
+# Fallback for newly installed photons (before shell restart)
+command_not_found_handler() {
+  if [ -f "$HOME/.photon/\$1.photon.ts" ] || [ -f "$HOME/.photon/\$1.photon.js" ]; then
+    photon cli "$@"
+    return $?
+  fi
+  echo "zsh: command not found: \$1" >&2
+  return 127
+}
+
+# Tab completion for photon methods, params, and instances
+_photon_cache="$HOME/.photon/cache/completions.cache"
+
+_photon_complete_direct() {
+  local cmd="\$words[1]"
+  local curcontext="\$curcontext" state line
+  _arguments -C "1: :->method" "*::arg:->params"
+  case "\$state" in
+    method)
+      if [[ -f "\$_photon_cache" ]]; then
+        local -a methods
+        methods=("\${(@f)$(grep "^method:\${cmd}:" "\$_photon_cache" | while IFS=: read -r _ _ name desc; do echo "\${name}:\${desc}"; done)}")
+        _describe 'method' methods
+      fi
+      ;;
+    params)
+      if [[ -f "\$_photon_cache" ]]; then
+        local method="\$line[1]"
+        local -a params
+        params=("\${(@f)$(grep "^param:\${cmd}:\${method}:" "\$_photon_cache" | while IFS=: read -r _ _ _ name type req; do echo "--\${name}[\${type}]"; done)}")
+        _describe 'parameter' params
+      fi
+      ;;
+  esac
+}
+
+# Register completion for each photon function (guard for non-interactive shells)
+if (( $+functions[compdef] )); then
+${photonNames.map((name) => `  compdef _photon_complete_direct ${name}`).join('\n')}
+fi
+
+# Completion for the photon command itself
+_photon() {
+  local curcontext="\$curcontext" state line
+  _arguments -C \\
+    "1: :->cmds" \\
+    "*::arg:->args"
+  case "\$state" in
+    cmds)
+      local -a builtins
+      builtins=(
+        'cli:Run a photon method'
+        'use:Switch to a named instance'
+        'instances:List instances of a photon'
+        'set:Configure environment for a photon'
+        'beam:Start the interactive UI'
+        'serve:Start MCP stdio server'
+        'list:List installed photons'
+        'add:Install a photon'
+        'remove:Uninstall a photon'
+        'search:Search for photons'
+        'info:Show photon details'
+        'shell:Shell integration'
+        'test:Run photon tests'
+        'doctor:Check system health'
+      )
+      _describe 'command' builtins
+      ;;
+    args)
+      case \$line[1] in
+        cli)
+          local curcontext="\$curcontext" state line
+          _arguments -C "1: :->photon_name" "*::arg:->method_args"
+          case "\$state" in
+            photon_name)
+              if [[ -f "\$_photon_cache" ]]; then
+                local -a photons
+                photons=("\${(@f)$(grep "^photon:" "\$_photon_cache" | while IFS=: read -r _ name desc; do echo "\${name}:\${desc}"; done)}")
+                _describe 'photon' photons
+              fi
+              ;;
+            method_args)
+              words[1]="\$line[1]"
+              _photon_complete_direct
+              ;;
+          esac
+          ;;
+        use|instances|set|info|serve)
+          if [[ -f "\$_photon_cache" ]]; then
+            local curcontext="\$curcontext" state line
+            _arguments -C "1: :->photon_name" "*::arg:->instance"
+            case "\$state" in
+              photon_name)
+                local -a photons
+                photons=("\${(@f)$(grep "^photon:" "\$_photon_cache" | while IFS=: read -r _ name desc; do echo "\${name}:\${desc}"; done)}")
+                _describe 'photon' photons
+                ;;
+              instance)
+                if [[ "\$line[-2]" == "use" ]]; then
+                  local -a instances
+                  instances=("\${(@f)$(grep "^instance:\${line[1]}:" "\$_photon_cache" | cut -d: -f3)}")
+                  [[ \${#instances} -gt 0 ]] && _describe 'instance' instances
+                fi
+                ;;
+            esac
+          fi
+          ;;
+        shell)
+          local -a subcmds
+          subcmds=('init:Set up shell integration' 'completions:Manage completion cache')
+          _describe 'subcommand' subcmds
+          ;;
+      esac
+      ;;
+  esac
+}
+
+if (( $+functions[compdef] )); then
+  compdef _photon photon
+fi`);
+        }
+        else if (shellType === 'bash') {
+            const functions = photonNames
+                .map((name) => `${name}() { photon cli ${name} "$@"; }`)
+                .join('\n');
+            console.log(`${marker}
+
+# Shell functions for installed photons (direct invocation)
+${functions}
+
+# Fallback for newly installed photons (before shell restart)
+command_not_found_handle() {
+  if [ -f "$HOME/.photon/\$1.photon.ts" ] || [ -f "$HOME/.photon/\$1.photon.js" ]; then
+    photon cli "$@"
+    return $?
+  fi
+  echo "bash: \$1: command not found" >&2
+  return 127
+}
+
+# Tab completion for photon methods, params, and instances
+_photon_cache="$HOME/.photon/cache/completions.cache"
+
+_photon_complete_direct() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local cmd="\${COMP_WORDS[0]}"
+  COMPREPLY=()
+
+  if [[ ! -f "\$_photon_cache" ]]; then return; fi
+
+  if [[ \$COMP_CWORD -eq 1 ]]; then
+    local methods
+    methods="$(grep "^method:\${cmd}:" "\$_photon_cache" | cut -d: -f3)"
+    COMPREPLY=($(compgen -W "\$methods" -- "\$cur"))
+  elif [[ \$COMP_CWORD -eq 2 ]]; then
+    local method="\${COMP_WORDS[1]}"
+    local params
+    params="$(grep "^param:\${cmd}:\${method}:" "\$_photon_cache" | cut -d: -f4 | sed 's/^/--/')"
+    COMPREPLY=($(compgen -W "\$params" -- "\$cur"))
+  fi
+}
+
+_photon_complete() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  COMPREPLY=()
+
+  if [[ ! -f "\$_photon_cache" ]]; then return; fi
+
+  if [[ \$COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "cli use instances set beam serve list add remove search info shell test doctor" -- "\$cur"))
+  elif [[ \$COMP_CWORD -eq 2 ]]; then
+    case "\${COMP_WORDS[1]}" in
+      cli|use|instances|set|info|serve)
+        local photons
+        photons="$(grep "^photon:" "\$_photon_cache" | cut -d: -f2)"
+        COMPREPLY=($(compgen -W "\$photons" -- "\$cur"))
+        ;;
+      shell)
+        COMPREPLY=($(compgen -W "init completions" -- "\$cur"))
+        ;;
+    esac
+  elif [[ \$COMP_CWORD -eq 3 ]]; then
+    case "\${COMP_WORDS[1]}" in
+      cli)
+        local methods
+        methods="$(grep "^method:\${COMP_WORDS[2]}:" "\$_photon_cache" | cut -d: -f3)"
+        COMPREPLY=($(compgen -W "\$methods" -- "\$cur"))
+        ;;
+      use)
+        local instances
+        instances="$(grep "^instance:\${COMP_WORDS[2]}:" "\$_photon_cache" | cut -d: -f3)"
+        COMPREPLY=($(compgen -W "\$instances" -- "\$cur"))
+        ;;
+    esac
+  elif [[ \$COMP_CWORD -ge 4 && "\${COMP_WORDS[1]}" == "cli" ]]; then
+    local params
+    params="$(grep "^param:\${COMP_WORDS[2]}:\${COMP_WORDS[3]}:" "\$_photon_cache" | cut -d: -f4 | sed 's/^/--/')"
+    COMPREPLY=($(compgen -W "\$params" -- "\$cur"))
+  fi
+}
+
+# Register completions
+${photonNames.map((name) => `complete -F _photon_complete_direct ${name}`).join('\n')}
+complete -F _photon_complete photon`);
+        }
+        else if (shellType === 'powershell') {
+            // PowerShell functions and completion
+            const functions = photonNames
+                .map((name) => `function ${name} { photon cli ${name} @Args }`)
+                .join('\n');
+            const functionNames = photonNames.map((n) => `'${n}'`).join(', ');
+            console.log(`${marker}
+
+# Functions for installed photons (direct invocation)
+${functions}
+
+# Fallback for newly installed photons (CommandNotFoundAction, PowerShell 7.4+)
+if ($PSVersionTable.PSVersion.Major -ge 7 -and $PSVersionTable.PSVersion.Minor -ge 4) {
+  $ExecutionContext.InvokeCommand.CommandNotFoundAction = {
+    param($Name, $EventArgs)
+    $photonFile = Join-Path $HOME ".photon" "$Name.photon.ts"
+    $photonFileJs = Join-Path $HOME ".photon" "$Name.photon.js"
+    if ((Test-Path $photonFile) -or (Test-Path $photonFileJs)) {
+      $EventArgs.CommandScriptBlock = { photon cli $Name @Args }.GetNewClosure()
+      $EventArgs.StopSearch = $true
+    }
+  }
+}
+
+# Tab completion for photon methods, params, and instances
+$_photonCache = Join-Path $HOME ".photon" "cache" "completions.cache"
+
+# Completion for direct photon commands
+${photonNames
+                .map((name) => `Register-ArgumentCompleter -CommandName ${name} -ScriptBlock {
+  param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
+  if (-not (Test-Path $_photonCache)) { return }
+  $pos = $commandAst.CommandElements.Count
+  if ($pos -le 1) {
+    # Complete method names
+    Get-Content $_photonCache | Where-Object { $_ -match "^method:\${commandName}:" } | ForEach-Object {
+      $parts = $_ -split ':', 4
+      [System.Management.Automation.CompletionResult]::new($parts[2], $parts[2], 'ParameterValue', ($parts[3] ?? $parts[2]))
+    } | Where-Object { $_.CompletionText -like "$wordToComplete*" }
+  } elseif ($pos -le 2) {
+    # Complete parameter names
+    $method = $commandAst.CommandElements[1].Value
+    Get-Content $_photonCache | Where-Object { $_ -match "^param:\${commandName}:\${method}:" } | ForEach-Object {
+      $parts = $_ -split ':', 6
+      $paramName = "--$($parts[3])"
+      [System.Management.Automation.CompletionResult]::new($paramName, $paramName, 'ParameterName', "$($parts[4]) parameter")
+    } | Where-Object { $_.CompletionText -like "$wordToComplete*" }
+  }
+}`)
+                .join('\n')}
+
+# Completion for the photon command itself
+Register-ArgumentCompleter -CommandName photon -ScriptBlock {
+  param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
+  $pos = $commandAst.CommandElements.Count
+  if ($pos -le 1) {
+    @('cli','use','instances','set','beam','serve','list','add','remove','search','info','shell','test','doctor') |
+      Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+  } elseif ($pos -le 2) {
+    $sub = $commandAst.CommandElements[1].Value
+    switch ($sub) {
+      { $_ -in 'cli','use','instances','set','info','serve' } {
+        if (Test-Path $_photonCache) {
+          Get-Content $_photonCache | Where-Object { $_ -match "^photon:" } | ForEach-Object {
+            $parts = $_ -split ':', 3
+            [System.Management.Automation.CompletionResult]::new($parts[1], $parts[1], 'ParameterValue', ($parts[2] ?? $parts[1]))
+          } | Where-Object { $_.CompletionText -like "$wordToComplete*" }
+        }
+      }
+      'shell' {
+        @('init','completions') | Where-Object { $_ -like "$wordToComplete*" } |
+          ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+      }
+    }
+  } elseif ($pos -le 3) {
+    $sub = $commandAst.CommandElements[1].Value
+    $photonName = $commandAst.CommandElements[2].Value
+    if ($sub -eq 'cli' -and (Test-Path $_photonCache)) {
+      Get-Content $_photonCache | Where-Object { $_ -match "^method:\${photonName}:" } | ForEach-Object {
+        $parts = $_ -split ':', 4
+        [System.Management.Automation.CompletionResult]::new($parts[2], $parts[2], 'ParameterValue', ($parts[3] ?? $parts[2]))
+      } | Where-Object { $_.CompletionText -like "$wordToComplete*" }
+    } elseif ($sub -eq 'use' -and (Test-Path $_photonCache)) {
+      Get-Content $_photonCache | Where-Object { $_ -match "^instance:\${photonName}:" } | ForEach-Object {
+        $parts = $_ -split ':', 3
+        [System.Management.Automation.CompletionResult]::new($parts[2], $parts[2], 'ParameterValue', $parts[2])
+      } | Where-Object { $_.CompletionText -like "$wordToComplete*" }
+    }
+  }
+}`);
+        }
+        // Silently generate cache on first hook (non-blocking)
+        const { CACHE_FILE } = await import('./shell-completions.js');
+        try {
+            await fs.access(CACHE_FILE);
+        }
+        catch {
+            // Cache doesn't exist yet — generate it
+            const { generateCompletionCache } = await import('./shell-completions.js');
+            await generateCompletionCache();
+        }
+        return;
+    }
+    // Interactive mode → install into rc file
+    try {
+        // Ensure profile directory exists (PowerShell profile dir may not)
+        const rcDir = path.dirname(rcFile);
+        await fs.mkdir(rcDir, { recursive: true });
+        let rcContent = '';
+        try {
+            rcContent = await fs.readFile(rcFile, 'utf-8');
+        }
+        catch {
+            // rc file doesn't exist, we'll create it
+        }
+        if (rcContent.includes(marker) || rcContent.includes(evalLine)) {
+            printInfo(`Shell integration already installed in ${rcFile}`);
+            if (shellType === 'powershell') {
+                console.log(`  Restart PowerShell or run: . $PROFILE`);
+            }
+            else {
+                console.log(`  Restart your shell or run: source ${rcFile}`);
+            }
+            return;
+        }
+        const block = `\n${marker}\n${evalLine}\n`;
+        await fs.appendFile(rcFile, block);
+        // Generate completions cache
+        const { generateCompletionCache } = await import('./shell-completions.js');
+        await generateCompletionCache();
+        printSuccess(`Installed shell integration into ${rcFile}`);
+        if (shellType === 'powershell') {
+            console.log(`  Restart PowerShell or run: . $PROFILE`);
+        }
+        else {
+            console.log(`  Restart your shell or run: source ${rcFile}`);
+        }
+        console.log('');
+        console.log(`  Then type any photon name directly:`);
+        console.log(`    list get          → photon cli list get`);
+        console.log(`    list add "Milk"   → photon cli list add "Milk"`);
+        console.log('');
+        console.log('  Tab completion is enabled for:');
+        console.log('    Photon names, methods, parameters, and instances.');
+    }
+    catch (error) {
+        printError(`Failed to update ${rcFile}: ${getErrorMessage(error)}`);
+        console.log(`  Add this line manually to your shell profile:`);
+        console.log(`    ${evalLine}`);
+        process.exit(1);
+    }
+});
+shell
+    .command('completions')
+    .option('--generate', 'Regenerate the completions cache')
+    .description('Manage shell completion cache')
+    .action(async (options) => {
+    const { generateCompletionCache, CACHE_FILE } = await import('./shell-completions.js');
+    if (options.generate) {
+        await generateCompletionCache();
+        printSuccess(`Completions cache updated: ${CACHE_FILE}`);
+        return;
+    }
+    // Default: show cache status
+    try {
+        const stat = await fs.stat(CACHE_FILE);
+        const age = Date.now() - stat.mtimeMs;
+        const ageStr = age < 60_000
+            ? 'just now'
+            : age < 3_600_000
+                ? `${Math.floor(age / 60_000)}m ago`
+                : `${Math.floor(age / 3_600_000)}h ago`;
+        printInfo(`Cache: ${CACHE_FILE}`);
+        console.log(`  Last updated: ${ageStr}`);
+        console.log(`  Run \`photon shell completions --generate\` to refresh`);
+    }
+    catch {
+        printInfo('No completions cache found.');
+        console.log('  Run `photon shell completions --generate` to create one.');
+    }
+});
+// Set command: configure environment for photons (primitive params without defaults)
+program
+    .command('set')
+    .argument('<photon>', 'Photon name')
+    .argument('[args...]', 'Environment values (name=value pairs)')
+    .description('Configure environment for a photon (params without defaults)')
+    .action(async (photonName, args) => {
+    try {
+        const workingDir = program.opts().dir || DEFAULT_WORKING_DIR;
+        // Resolve photon path
+        const filePath = await resolvePhotonPathWithBundled(photonName, workingDir);
+        if (!filePath) {
+            printError(`Photon not found: ${photonName}`);
+            process.exit(1);
+        }
+        // Extract constructor params and filter env params
+        const allParams = await extractConstructorParams(filePath);
+        const { getEnvParams, EnvStore } = await import('./context-store.js');
+        const envParams = getEnvParams(allParams);
+        if (envParams.length === 0) {
+            printInfo(`${photonName} has no environment parameters.`);
+            return;
+        }
+        const store = new EnvStore();
+        // Parse name=value pairs from args
+        const values = {};
+        const paramNames = new Set(envParams.map((p) => p.name));
+        for (const arg of args) {
+            const eqIdx = arg.indexOf('=');
+            if (eqIdx > 0) {
+                const key = arg.slice(0, eqIdx);
+                const val = arg.slice(eqIdx + 1);
+                if (paramNames.has(key)) {
+                    values[key] = val;
+                }
+            }
+            else if (envParams.length === 1) {
+                // Single env param: positional value
+                values[envParams[0].name] = arg;
+            }
+        }
+        // Find params that still need values
+        const remaining = envParams.filter((p) => !(p.name in values));
+        if (remaining.length > 0) {
+            // Interactive mode for remaining params
+            cliHeading(`${photonName} — Environment`);
+            cliSpacer();
+            const masked = store.getMasked(photonName);
+            for (const param of remaining) {
+                const currentDisplay = masked[param.name] ? `Current: ${masked[param.name]}` : 'Not set';
+                const answer = await promptText(`  ${param.name} (required)\n  ${currentDisplay}\n  > `);
+                if (answer.trim() !== '') {
+                    values[param.name] = answer.trim();
+                }
+            }
+        }
+        if (Object.keys(values).length > 0) {
+            store.write(photonName, values);
+            const summary = Object.keys(values).join(', ');
+            printSuccess(`Environment saved: ${summary}`);
+        }
+        else {
+            printInfo('No changes.');
+        }
+    }
+    catch (error) {
+        printError(getErrorMessage(error));
+        process.exit(1);
+    }
+});
 // Alias commands: create CLI shortcuts for photons
 program
     .command('alias', { hidden: true })
@@ -1908,6 +2511,10 @@ const RESERVED_COMMANDS = [
     'doctor',
     'clear-cache',
     'clean',
+    // Instance/env
+    'use',
+    'instances',
+    'set',
     // Aliases
     'cli',
     'alias',
@@ -1922,6 +2529,7 @@ const RESERVED_COMMANDS = [
     'search',
     'maker',
     'host',
+    'shell',
     'diagram',
     'diagrams',
     'enable',
@@ -1956,6 +2564,9 @@ const knownCommands = [
     'clear-cache',
     'clean',
     'doctor',
+    'use',
+    'instances',
+    'set',
     'cli',
     'alias',
     'unalias',
@@ -1965,12 +2576,14 @@ const knownCommands = [
     'marketplace',
     'maker',
     'host',
+    'shell',
     'diagram',
     'diagrams',
 ];
 const knownSubcommands = {
     marketplace: ['list', 'add', 'remove', 'enable', 'disable'],
     maker: ['new', 'validate', 'sync', 'init'],
+    shell: ['init', 'completions'],
 };
 /**
  * Calculate Levenshtein distance between two strings
@@ -2048,9 +2661,10 @@ program.on('command:*', async (operands) => {
 // This enables: `photon lg-remote volume +5` instead of `photon cli lg-remote volume +5`
 function preprocessArgs() {
     const args = process.argv.slice(2);
-    // No args - default to beam with auto-open browser
+    // No args - launch Beam (the primary interface)
+    // Use `photon -h` or `photon --help` for help
     if (args.length === 0) {
-        return [...process.argv, 'beam', '--open'];
+        return [...process.argv, 'beam'];
     }
     // Find the first non-flag argument (skip values of flags that take a parameter)
     const flagsWithValues = ['--dir', '--log-level'];
@@ -2068,8 +2682,8 @@ function preprocessArgs() {
         if (args.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V')) {
             return process.argv;
         }
-        // Otherwise default to beam (e.g., photon --dir=. → photon --dir=. beam --open)
-        return [...process.argv, 'beam', '--open'];
+        // Otherwise launch Beam (e.g., photon --dir=.)
+        return [...process.argv, 'beam'];
     }
     const firstArg = args[firstArgIndex];
     // If first arg is a reserved command, let commander handle normally