@atollhq/skill-codex 0.4.22 → 0.4.24

package/README.md

@@ -6,13 +6,27 @@ Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, mi
 
 ## Install
 
+Install or refresh the local skill files without configuring credentials:
+
+```bash
+npx --yes @atollhq/skill-codex@latest
+```
+
+Bare invocation and `--install-only` only update `~/.codex/skills/atoll/`, the profile-neutral routing hint, and compatibility references. They do not inspect or change Atoll credentials, profiles, shell files, or repo configuration, even when `ATOLL_*` variables are present.
+
+Configure a named profile explicitly:
+
+```bash
+npx --yes @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-id --team team-id
+```
+
+For intentional environment configuration, use `--configure`:
+
 ```bash
-npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-org-id --project project-id --team team-id
-# or
-ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex@latest
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid npx --yes @atollhq/skill-codex@latest --configure
 ```
 
-Optional defaults: `--project`, `--team`, and `--base-url` are stored with the selected mode. Use `--no-project`, `--no-team`, or `--no-base-url` to clear previously saved defaults. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports to `~/.zshrc` or `~/.bashrc` in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands, or omit `--profile` to use env-var mode.
+Configuration mode supports `--project`, `--team`, and `--base-url`. Use `--no-project`, `--no-team`, or `--no-base-url` to clear saved defaults. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands.
 
 For multi-org setups, keep global Codex instructions neutral and bind profiles per repo:
 
@@ -23,18 +37,18 @@ npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-
 
 `--write-project-instructions` writes a small managed block to repo-local instruction files. It requires `--profile`, defaults to the current directory, writes `AGENTS.md` by default, and can also write `CLAUDE.md` with `--instruction-files agents,claude`. If the target file already has unmanaged Atoll profile guidance, pass `--force-project-instructions` after reviewing the replacement.
 
-Get an agent API key from **Agents** in the Atoll app. Integration keys are still managed from **Settings > Members**.
+Get an agent API key from **Agents** in the Atoll app. Integration keys are managed from **Settings > Integrations**.
 
-This does six things:
+Every invocation installs the local skill assets, routing hint, and compatibility references. Configuration mode additionally:
 
 1. Installs the `atoll` skill to `~/.codex/skills/atoll/`
 2. Appends (or updates) a small profile-neutral Atoll skill routing hint in `~/.codex/AGENTS.md`
 3. Copies API reference files to `~/.codex/atoll-references/`
 4. Creates or updates the named Atoll CLI profile when `--profile` is provided
-5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) only when no profile is provided
+5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) when `--configure` is used without a profile
 6. Optionally writes repo-local profile guidance when `--write-project-instructions` is provided
 
-For profile mode, Codex has the Atoll skill immediately, global Codex guidance points to that skill without embedding the full Atoll guide, and terminal commands can use `atoll --profile agent-a ...`. For env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
+For profile mode, Codex has the Atoll skill immediately, global Codex guidance points to that skill without embedding the full Atoll guide, and terminal commands can use `atoll --profile agent-a ...`. For explicitly requested env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
 
 Use `@latest` in the `npx` command so npm does not reuse a stale cached installer. In profile mode, the installer prints its package version and a verification command; run `atoll --profile agent-a agent-context --json` if you need to confirm the profile was created.
 

package/bin/install.mjs

@@ -22,45 +22,86 @@ import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'))
+const configurationFlags = new Set([
+  '--configure',
+  '--profile',
+  '--key',
+  '--org',
+  '--project',
+  '--no-project',
+  '--team',
+  '--no-team',
+  '--base-url',
+  '--no-base-url',
+  '--write-project-instructions',
+  '--project-dir',
+  '--instruction-files',
+  '--force-project-instructions',
+])
+const valueFlags = {
+  '--profile': 'profile',
+  '--key': 'key',
+  '--org': 'org',
+  '--project': 'project',
+  '--team': 'team',
+  '--base-url': 'baseUrl',
+  '--project-dir': 'projectDir',
+  '--instruction-files': 'instructionFiles',
+}
+
+function hasConfigurationIntent(argv) {
+  return argv.slice(2).some((arg) => configurationFlags.has(arg.split('=', 1)[0]))
+}
 
 function parseArgs(argv) {
   const args = {}
   for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === '--profile' && argv[i + 1]) args.profile = argv[++i]
-    else if (argv[i] === '--key' && argv[i + 1]) args.key = argv[++i]
-    else if (argv[i] === '--org' && argv[i + 1]) args.org = argv[++i]
-    else if (argv[i] === '--project' && argv[i + 1]) args.project = argv[++i]
-    else if (argv[i] === '--no-project') args.clearProject = true
-    else if (argv[i] === '--team' && argv[i + 1]) args.team = argv[++i]
-    else if (argv[i] === '--no-team') args.clearTeam = true
-    else if (argv[i] === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i]
-    else if (argv[i] === '--no-base-url') args.clearBaseUrl = true
-    else if (argv[i] === '--write-project-instructions') args.writeProjectInstructions = true
-    else if (argv[i] === '--project-dir' && argv[i + 1]) args.projectDir = argv[++i]
-    else if (argv[i] === '--instruction-files' && argv[i + 1]) args.instructionFiles = argv[++i]
-    else if (argv[i] === '--force-project-instructions') args.forceProjectInstructions = true
-    else if (argv[i] === '--help' || argv[i] === '-h') args.help = true
+    const argument = argv[i]
+    const separator = argument.indexOf('=')
+    const flag = separator === -1 ? argument : argument.slice(0, separator)
+    const inlineValue = separator === -1 ? undefined : argument.slice(separator + 1)
+    const nextValue = inlineValue ?? argv[i + 1]
+    const valueKey = valueFlags[flag]
+    if (valueKey) {
+      if (!nextValue || nextValue.startsWith('-')) {
+        throw new Error(`${flag} requires a non-empty value`)
+      }
+      args[valueKey] = nextValue
+      if (inlineValue === undefined) i++
+    } else if (flag === '--no-project') args.clearProject = true
+    else if (flag === '--no-team') args.clearTeam = true
+    else if (flag === '--no-base-url') args.clearBaseUrl = true
+    else if (flag === '--install-only') args.installOnly = true
+    else if (flag === '--configure') args.configure = true
+    else if (flag === '--write-project-instructions') args.writeProjectInstructions = true
+    else if (flag === '--force-project-instructions') args.forceProjectInstructions = true
+    else if (flag === '--help' || flag === '-h') args.help = true
+    else throw new Error(`Unknown option: ${flag}`)
   }
   return args
 }
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-codex@latest [--profile <name>] --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
-   or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex@latest
+Usage: npx @atollhq/skill-codex@latest --install-only
+   or: npx @atollhq/skill-codex@latest --configure [--profile <name>] --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
+   or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex@latest --configure
 
 Options:
-  --profile   Atoll CLI profile name to create/update. Profile mode does not write shell env vars.
-  --key       Atoll API key (sk_atoll_...). Defaults to ATOLL_API_KEY.
-  --org       Organization ID. Defaults to ATOLL_ORG_ID.
-  --project   Default project ID. Defaults to ATOLL_PROJECT.
+  --profile   Atoll CLI profile name to create/update. Enables configuration mode.
+  --key       Atoll API key (sk_atoll_...). Used in configuration mode; defaults to ATOLL_API_KEY.
+  --org       Organization ID. Used in configuration mode; defaults to ATOLL_ORG_ID.
+  --project   Default project ID. Used in configuration mode; defaults to ATOLL_PROJECT.
   --no-project Clear any saved default project.
-  --team      Default team ID or slug. Defaults to ATOLL_TEAM.
+  --team      Default team ID or slug. Used in configuration mode; defaults to ATOLL_TEAM.
   --no-team   Clear any saved default team.
-  --base-url  Atoll base URL. Defaults to ATOLL_BASE_URL.
+  --base-url  Atoll base URL. Used in configuration mode; defaults to ATOLL_BASE_URL.
   --no-base-url Clear any saved custom base URL.
+  --install-only
+              Install or refresh local skill files without reading or changing credentials.
+  --configure Explicitly enable profile or environment credential configuration.
   --write-project-instructions
-              Write a small repo-local Atoll profile block. Requires --profile.
+              Write a small repo-local Atoll profile block. Requires --configure and --profile.
   --project-dir
               Directory for repo-local instructions. Defaults to the current directory.
   --instruction-files
@@ -72,24 +113,35 @@ Options:
 Installs the Atoll integration for Codex CLI:
   - Installs the atoll skill to ~/.codex/skills/atoll/
   - Writes a small AGENTS.md routing hint to ~/.codex/
-  - Creates/updates an Atoll CLI profile when --profile is provided
+  - Leaves authentication and profile configuration unchanged by default
+  - Creates/updates credentials only when --configure or another configuration flag is provided
   - Optionally writes repo-local AGENTS.md/CLAUDE.md profile guidance with --write-project-instructions
-  - Otherwise writes Atoll env vars to your shell profile for env-var mode
 `)
 }
 
 const args = parseArgs(process.argv)
-args.key ??= process.env.ATOLL_API_KEY
-args.org ??= process.env.ATOLL_ORG_ID
-if (args.clearProject) delete args.project
-else args.project ??= process.env.ATOLL_PROJECT
-if (args.clearTeam) delete args.team
-else args.team ??= process.env.ATOLL_TEAM
-if (args.clearBaseUrl) delete args.baseUrl
-else args.baseUrl ??= process.env.ATOLL_BASE_URL
+const configurationIntent = hasConfigurationIntent(process.argv)
+
+if (args.installOnly && configurationIntent) {
+  console.error('Error: --install-only cannot be combined with credential or profile configuration flags')
+  printUsage()
+  process.exit(1)
+}
 
 if (args.help) { printUsage(); process.exit(0) }
 
+const configureMode = configurationIntent
+if (configureMode) {
+  args.key ??= process.env.ATOLL_API_KEY
+  args.org ??= process.env.ATOLL_ORG_ID
+  if (args.clearProject) delete args.project
+  else args.project ??= process.env.ATOLL_PROJECT
+  if (args.clearTeam) delete args.team
+  else args.team ??= process.env.ATOLL_TEAM
+  if (args.clearBaseUrl) delete args.baseUrl
+  else args.baseUrl ??= process.env.ATOLL_BASE_URL
+}
+
 console.log(`Running @atollhq/skill-codex installer v${packageJson.version}`)
 
 const instructionFileChoices = (args.instructionFiles ?? 'agents')
@@ -118,13 +170,13 @@ if (args.writeProjectInstructions && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args.p
   process.exit(1)
 }
 
-if (!args.key || !args.org) {
+if (configureMode && (!args.key || !args.org)) {
   console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
   process.exit(1)
 }
 
-if (!args.key.startsWith('sk_atoll_')) {
+if (configureMode && !args.key.startsWith('sk_atoll_')) {
   console.error('Error: API key must start with sk_atoll_')
   process.exit(1)
 }
@@ -164,6 +216,52 @@ function ensurePrivateDirectory(path) {
   chmodSync(path, 0o700)
 }
 
+function prepareSkillDirectory(path, source) {
+  const existing = lstatIfExists(path)
+  if (existing) {
+    if (existing.isSymbolicLink()) {
+      throw new Error(`Refusing symbolic link for skill directory: ${path}`)
+    }
+    if (!existing.isDirectory()) {
+      throw new Error(`Refusing non-directory skill path: ${path}`)
+    }
+  }
+
+  const parent = dirname(path)
+  mkdirSync(parent, { recursive: true })
+  const tempPath = join(parent, `.${basename(path)}.atoll-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`)
+  const backupPath = `${tempPath}.backup`
+  let movedExisting = false
+  let installed = false
+  try {
+    cpSync(source, tempPath, { recursive: true })
+
+    const current = lstatIfExists(path)
+    if (current) {
+      if (current.isSymbolicLink()) {
+        throw new Error(`Refusing symbolic link for skill directory: ${path}`)
+      }
+      if (!current.isDirectory()) {
+        throw new Error(`Refusing non-directory skill path: ${path}`)
+      }
+      renameSync(path, backupPath)
+      movedExisting = true
+    }
+
+    renameSync(tempPath, path)
+    installed = true
+    if (movedExisting) rmSync(backupPath, { recursive: true, force: true })
+  } catch (error) {
+    if (!installed) {
+      if (lstatIfExists(tempPath)) rmSync(tempPath, { recursive: true, force: true })
+      if (movedExisting && !lstatIfExists(path) && lstatIfExists(backupPath)) {
+        renameSync(backupPath, path)
+      }
+    }
+    throw error
+  }
+}
+
 function readJson(path) {
   assertSafeFile(path)
   if (!existsSync(path)) return {}
@@ -198,10 +296,27 @@ function writePrivateFile(path, content) {
   }
 }
 
-function acquireInstallerLock() {
-  const atollDir = join(homedir(), '.atoll')
-  const target = join(atollDir, 'installer.lock-target')
-  ensurePrivateDirectory(atollDir)
+const codexDir = resolve(process.env.CODEX_HOME || join(homedir(), '.codex'))
+const defaultInstallerLockTarget = join(homedir(), '.atoll', 'installer.lock-target')
+const sharedInstallerLockTarget = join(
+  homedir(),
+  '.atoll-skill-installer.lock-target',
+)
+const codexSkillLockTarget = join(codexDir, '.atoll-skill-installer.lock-target')
+
+function ensureLockDirectory(path) {
+  const entry = lstatIfExists(path)
+  if (entry) {
+    const stat = entry.isSymbolicLink() ? statSync(path) : entry
+    if (!stat.isDirectory()) throw new Error(`Refusing non-directory installer lock path: ${path}`)
+  } else {
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+  }
+}
+
+function acquireInstallerLock(target = defaultInstallerLockTarget) {
+  if (target === defaultInstallerLockTarget) ensurePrivateDirectory(dirname(target))
+  else ensureLockDirectory(dirname(target))
   try {
     writeFileSync(target, '', { flag: 'wx', mode: 0o600 })
   } catch (error) {
@@ -257,7 +372,23 @@ function acquireInstallerLock() {
   }
 }
 
-const releaseInstallerLock = acquireInstallerLock()
+const releaseSharedInstallerLock = acquireInstallerLock(sharedInstallerLockTarget)
+let releaseCodexSkillInstallerLock = null
+let releaseConfigInstallerLock = null
+try {
+  releaseCodexSkillInstallerLock = acquireInstallerLock(codexSkillLockTarget)
+  if (configureMode) releaseConfigInstallerLock = acquireInstallerLock()
+} catch (error) {
+  releaseCodexSkillInstallerLock?.()
+  releaseSharedInstallerLock()
+  throw error
+}
+
+function releaseInstallerLock() {
+  releaseConfigInstallerLock?.()
+  releaseCodexSkillInstallerLock?.()
+  releaseSharedInstallerLock()
+}
 
 function writeAtollProfile() {
   if (!args.profile) return null
@@ -422,14 +553,12 @@ function writeGlobalInstructions(targetPath) {
 }
 
 // 1. Install the Codex skill to ~/.codex/skills/atoll/
-const codexDir = join(homedir(), '.codex')
 mkdirSync(codexDir, { recursive: true })
 
 const skillDir = join(__dirname, '..', 'skill')
 const skillDest = join(codexDir, 'skills', 'atoll')
 const legacySkillDest = join(codexDir, 'skills', 'atoll-api')
-mkdirSync(skillDest, { recursive: true })
-cpSync(skillDir, skillDest, { recursive: true })
+prepareSkillDirectory(skillDest, skillDir)
 console.log(`Installed Atoll skill to ${skillDest}`)
 if (existsSync(legacySkillDest)) {
   rmSync(legacySkillDest, { recursive: true, force: true })
@@ -449,6 +578,13 @@ for (const file of ['api-endpoints.md', 'api-fields.md']) {
 }
 console.log(`Copied API references to ${refsDir}`)
 
+if (!configureMode) {
+  console.log('Authentication/profile configuration left unchanged.')
+  console.log('\nDone! Codex has the Atoll skill installed.')
+  releaseInstallerLock()
+  process.exit(0)
+}
+
 const shell = process.env.SHELL || '/bin/bash'
 const profilePath = shell.includes('zsh')
   ? join(homedir(), '.zshrc')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"