@atollhq/skill-claude 0.4.23 → 0.4.24

package/README.md

@@ -6,17 +6,31 @@ Gives your Claude Code agent the ability to manage tasks, goals, KPIs, initiativ
 
 ## Install
 
+Install or refresh the local skill files without configuring credentials:
+
+```bash
+npx --yes @atollhq/skill-claude@latest
+```
+
+Bare invocation and `--install-only` only update `~/.claude/skills/atoll/`. They do not inspect or change Atoll credentials, profiles, shell files, or Claude settings, even when `ATOLL_*` variables are present.
+
+Configure a named profile explicitly:
+
+```bash
+npx --yes @atollhq/skill-claude@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-claude@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-claude@latest
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=org-uuid npx --yes @atollhq/skill-claude@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 a global `ATOLL_PROFILE` or `ATOLL_*` credential settings in profile mode, so direct CLI commands should use `atoll --profile agent-a ...`. Omit `--profile` to use env-var mode, which writes `ATOLL_ENV_MODE=1` with the credential settings.
+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 a global `ATOLL_PROFILE` or `ATOLL_*` credential setting in profile mode, so direct CLI commands should use `atoll --profile agent-a ...`.
 
 Get an agent API key from **Agents** in the Atoll app. Integration keys are managed from **Settings > Integrations**.
 
-This does three things:
+Every invocation copies the skill. Configuration mode additionally:
 
 1. Copies the skill into `~/.claude/skills/atoll/`
 2. Removes stale Atoll credential/profile env from `~/.claude/settings.json` when profile mode is used

package/bin/install.mjs

@@ -11,6 +11,7 @@ import {
   readFileSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
@@ -20,30 +21,60 @@ 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',
+])
+const valueFlags = {
+  '--profile': 'profile',
+  '--key': 'key',
+  '--org': 'org',
+  '--project': 'project',
+  '--team': 'team',
+  '--base-url': 'baseUrl',
+}
+
+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') {
+    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 (argv[i] === '--team' && argv[i + 1]) {
-      args.team = argv[++i]
-    } else if (argv[i] === '--no-team') {
+    } else if (flag === '--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') {
+    } else if (flag === '--no-base-url') {
       args.clearBaseUrl = true
-    } else if (argv[i] === '--help' || argv[i] === '-h') {
+    } else if (flag === '--install-only') {
+      args.installOnly = true
+    } else if (flag === '--configure') {
+      args.configure = true
+    } else if (flag === '--help' || flag === '-h') {
       args.help = true
+    } else {
+      throw new Error(`Unknown option: ${flag}`)
     }
   }
   return args
@@ -51,50 +82,67 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-claude@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-claude@latest
+Usage: npx @atollhq/skill-claude@latest --install-only
+   or: npx @atollhq/skill-claude@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-claude@latest --configure
 
 Options:
-  --profile   Atoll CLI profile name to create/update.
-  --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.
   --help      Show this help message
 
 This installs the Atoll skill for Claude Code, giving your agent
-the ability to manage tasks, goals, KPIs, and initiatives.
+the ability to manage tasks, goals, KPIs, and initiatives. Authentication
+and profile configuration remain unchanged unless --configure or another
+configuration flag is provided.
 `)
 }
 
 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-claude installer v${packageJson.version}`)
 
-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)
 }
@@ -134,6 +182,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 {}
@@ -163,10 +257,22 @@ function writePrivateFile(path, content) {
   }
 }
 
-function acquireInstallerLock() {
-  const atollDir = join(homedir(), '.atoll')
-  const target = join(atollDir, 'installer.lock-target')
-  ensurePrivateDirectory(atollDir)
+const defaultInstallerLockTarget = join(homedir(), '.atoll', 'installer.lock-target')
+const sharedInstallerLockTarget = join(homedir(), '.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) {
@@ -222,7 +328,19 @@ function acquireInstallerLock() {
   }
 }
 
-const releaseInstallerLock = acquireInstallerLock()
+const releaseSharedInstallerLock = acquireInstallerLock(sharedInstallerLockTarget)
+let releaseConfigInstallerLock = null
+try {
+  if (configureMode) releaseConfigInstallerLock = acquireInstallerLock()
+} catch (error) {
+  releaseSharedInstallerLock()
+  throw error
+}
+
+function releaseInstallerLock() {
+  releaseConfigInstallerLock?.()
+  releaseSharedInstallerLock()
+}
 
 function writeAtollProfile() {
   if (!args.profile) return
@@ -255,14 +373,20 @@ const skillDest = join(homedir(), '.claude', 'skills', 'atoll')
 const legacySkillDest = join(homedir(), '.claude', 'skills', 'atoll-api')
 ensurePrivateDirectory(join(homedir(), '.claude'))
 
-mkdirSync(join(skillDest, 'references'), { recursive: true })
-cpSync(skillSrc, skillDest, { recursive: true })
+prepareSkillDirectory(skillDest, skillSrc)
 console.log(`Installed skill to ${skillDest}`)
 if (existsSync(legacySkillDest)) {
   rmSync(legacySkillDest, { recursive: true, force: true })
   console.log(`Removed legacy Atoll skill at ${legacySkillDest}`)
 }
 
+if (!configureMode) {
+  console.log('Authentication/profile configuration left unchanged.')
+  console.log('\nDone! Start Claude Code and the atoll skill will be available.')
+  releaseInstallerLock()
+  process.exit(0)
+}
+
 // 2. Configure ~/.claude/settings.json. Profile mode stores credentials only
 // in the Atoll CLI profile and removes stale credential/profile env from
 // earlier installs so a new profile install does not become globally active.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.23",
+  "version": "0.4.24",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"