ace-pack 0.1.0 → 0.1.2

package/README.md

@@ -40,8 +40,8 @@ ACE turns those soft expectations into local project structure:
 - `AGENTS.md` keeps stack, architecture, and workflow rules close to the code.
 - `.ai/memory-config.json` marks high-risk paths and keywords for the current
   repository.
-- `ace:validate` stays project-owned so every repo can define its real
-  mechanical quality gate.
+- `ace:validate` starts as an ACE memory check and can be replaced by each
+  repo with its real mechanical quality gate.
 
 ## ACE vs. Just Chatting With AI
 
@@ -100,33 +100,62 @@ applied.
 
 ## Quick Start
 
-Install ACE into the current repository:
+Install ACE into the current repository. Use `init`; do not use
+`npm install ace-pack` for project setup.
 
 ```bash
-pnpm dlx ace-pack init
+npx ace-pack@latest init
+```
+
+Then profile the project:
+
+```bash
+npm run ace:onboard -- --apply
+npm run ace:check
 ```
 
-Or with npm:
+Prefer pnpm? Use the same flow through `pnpm dlx`:
 
 ```bash
-npx ace-pack init
+pnpm dlx ace-pack init
+pnpm ace:onboard -- --apply
+pnpm ace:check
 ```
 
 Install into another repository:
 
 ```bash
-pnpm dlx ace-pack init ./my-project
+npx ace-pack@latest init ./my-project
 ```
 
-Profile the project:
+Install and apply onboarding in one command:
 
 ```bash
-pnpm ace:onboard
-pnpm ace:onboard -- --apply
+npx ace-pack@latest init --apply
 ```
 
+Need help?
+
+```bash
+npx ace-pack@latest --help
+npx ace-pack@latest init --help
+```
+
+## What Init Does
+
+`ace-pack init` adds or updates local project files:
+
+- `AGENTS.md` and `CLAUDE.md`
+- `.ai/*` memory, task, handoff, decisions, and profile files
+- `scripts/*` ACE automation copied into the project
+- `package.json` commands such as `ace:onboard`, `ace:classify`,
+  `ace:validate`, `ace:finish`, and `ace:hub`
+
+ACE does not need to remain installed as a runtime dependency. The npm package
+acts as a scaffold CLI, then the project owns the copied scripts.
+
 For Python, Go, Rust, .NET, or any repo without `package.json`, ACE creates a
-lightweight private runner package:
+lightweight private runner package so the same commands are available:
 
 ```json
 {
@@ -134,8 +163,14 @@ lightweight private runner package:
 }
 ```
 
-No dependency install is required for ACE itself. The runner only exposes
-commands such as `ace:onboard`, `ace:hub`, `ace:classify`, and `ace:finish`.
+On Windows PowerShell, use `pnpm.cmd` if script execution policy blocks the
+regular `pnpm` shim:
+
+```bash
+pnpm.cmd dlx ace-pack init
+pnpm.cmd ace:onboard -- --apply
+pnpm.cmd ace:check
+```
 
 Known SaaS monorepo? Apply the built-in preset:
 
@@ -199,7 +234,7 @@ pnpm ace:classify
 | `ace:onboard -- --preset next-trpc-drizzle-saas --apply` | Applies the built-in Next.js + tRPC + Drizzle SaaS profile. |
 | `ace:onboard -- --check` | Fails if the repository is still unprofiled. |
 | `ace:classify` | Git diff risk analysis for small, standard, and large tasks. |
-| `ace:validate` | Project-owned mechanical quality gate. ACE never overwrites this script. |
+| `ace:validate` | Default mechanical quality gate alias for `ace:check`. Projects may replace it with a stricter local gate. |
 | `ace:finish` | Adaptive closeout, memory documentation, reports, and reflection. |
 | `ace:hub` | Interactive context generator for copying focused project context into AI tools. |
 

package/install-ace-pack.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { access, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { onboardRepository } from './scripts/ace-onboard.mjs'
 import { ensureAgentMemory } from './scripts/agent-memory-lib.mjs'
 
 const REQUIRED_PACKAGE_SCRIPTS = {
@@ -29,6 +30,10 @@ const REQUIRED_PACKAGE_SCRIPTS = {
   'ai:update:changed': 'node ./scripts/ai-update.mjs changed',
 }
 
+const DEFAULT_PACKAGE_SCRIPTS = {
+  'ace:validate': 'node ./scripts/check-agent-memory.mjs',
+}
+
 const MANAGED_SCRIPT_FILES = [
   'ace-hub.mjs',
   'ace-onboard.mjs',
@@ -61,6 +66,7 @@ const currentFilePath = fileURLToPath(import.meta.url)
 const currentScriptDir = path.join(path.dirname(currentFilePath), 'scripts')
 const RUNNER_PACKAGE_DESCRIPTION =
   'Auto-generated lightweight runner for ACE (Agentic Context Engine) scripts. No node_modules required.'
+const KNOWN_PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun'])
 
 function normalizeTrailingNewline(content) {
   return content.endsWith('\n') ? content : `${content}\n`
@@ -78,6 +84,19 @@ async function readTextIfExists(filePath) {
   }
 }
 
+async function fileExists(filePath) {
+  try {
+    await access(filePath)
+    return true
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return false
+    }
+
+    throw error
+  }
+}
+
 async function ensureDefaultAgentsFile(rootDir) {
   const agentsPath = path.join(rootDir, 'AGENTS.md')
   const existingContent = await readTextIfExists(agentsPath)
@@ -135,6 +154,15 @@ async function ensurePackageScripts(rootDir) {
     changed = true
   }
 
+  for (const [scriptName, scriptValue] of Object.entries(DEFAULT_PACKAGE_SCRIPTS)) {
+    if (scriptName in nextScripts) {
+      continue
+    }
+
+    nextScripts[scriptName] = scriptValue
+    changed = true
+  }
+
   if (!changed) {
     return false
   }
@@ -218,24 +246,202 @@ export async function installAcePack(targetDir) {
   createdFiles.push(...memoryResult.createdFiles)
   updatedFiles.push(...memoryResult.updatedFiles)
 
+  const createdFileSet = new Set(createdFiles)
+
   return {
     createdFiles,
     targetDir: normalizedTargetDir,
-    updatedFiles,
+    updatedFiles: updatedFiles.filter((filePath) => !createdFileSet.has(filePath)),
   }
 }
 
 export function resolveTargetDir(args, cwd = process.cwd()) {
-  const [commandOrTarget, maybeTarget] = args
+  return parseInstallArgs(args, cwd).targetDir
+}
+
+export function parseInstallArgs(args, cwd = process.cwd()) {
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    return {
+      apply: false,
+      help: true,
+      preset: null,
+      targetDir: cwd,
+    }
+  }
+
+  const remainingArgs = [...args]
+
+  if (remainingArgs[0] === 'init') {
+    remainingArgs.shift()
+  }
+
+  let apply = false
+  let preset = null
+  let target = null
+
+  for (let index = 0; index < remainingArgs.length; index += 1) {
+    const arg = remainingArgs[index]
 
-  if (commandOrTarget === 'init') {
-    return maybeTarget ? path.resolve(cwd, maybeTarget) : cwd
+    if (arg === '--') {
+      continue
+    }
+
+    if (arg === '--apply') {
+      apply = true
+      continue
+    }
+
+    if (arg === '--no-apply') {
+      apply = false
+      continue
+    }
+
+    if (arg === '--preset') {
+      const nextArg = remainingArgs[index + 1]
+
+      if (!nextArg || nextArg.startsWith('-')) {
+        throw new Error('Missing value for --preset.')
+      }
+
+      preset = nextArg
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith('--preset=')) {
+      preset = arg.slice('--preset='.length)
+
+      if (!preset) {
+        throw new Error('Missing value for --preset.')
+      }
+
+      continue
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`)
+    }
+
+    if (target !== null) {
+      throw new Error(`Unexpected extra argument: ${arg}`)
+    }
+
+    target = arg
+  }
+
+  if (preset && !apply) {
+    throw new Error('Use --preset together with --apply.')
   }
 
-  return commandOrTarget ? path.resolve(cwd, commandOrTarget) : cwd
+  return {
+    apply,
+    help: false,
+    preset,
+    targetDir: path.resolve(cwd, target ?? '.'),
+  }
 }
 
-export function printInstallResult(result) {
+export function getHelpText(commandName = 'ace-pack') {
+  return `ACE Pack - install AI project memory into a repository.
+
+Usage:
+  ${commandName} init [target] [--apply] [--preset <name>]
+  ${commandName} [target]
+
+Recommended:
+  npx ace-pack@latest init
+  pnpm dlx ace-pack init
+
+Options:
+  --apply            Run ace:onboard -- --apply after installation.
+  --preset <name>    Apply a built-in project preset during onboarding.
+  -h, --help         Show this help.
+
+Examples:
+  npx ace-pack@latest init
+  npx ace-pack@latest init D:\\All\\alex-work\\my-project --apply
+  pnpm dlx ace-pack init . --apply
+
+Do not use npm install ace-pack for setup. ACE is a scaffold CLI: run init so it
+can add AGENTS.md, .ai/*, scripts/*, and package.json commands to the project.
+`
+}
+
+function getPackageManagerFromPackageJson(packageJson) {
+  if (typeof packageJson.packageManager !== 'string') {
+    return null
+  }
+
+  const packageManagerName = packageJson.packageManager.split('@')[0]
+
+  return KNOWN_PACKAGE_MANAGERS.has(packageManagerName) ? packageManagerName : null
+}
+
+function getPackageManagerFromUserAgent(userAgent = process.env.npm_config_user_agent) {
+  if (!userAgent) {
+    return null
+  }
+
+  const packageManagerName = userAgent.split('/')[0]
+
+  return KNOWN_PACKAGE_MANAGERS.has(packageManagerName) ? packageManagerName : null
+}
+
+export async function detectPackageManager(rootDir) {
+  const packageJsonContent = await readTextIfExists(path.join(rootDir, 'package.json'))
+
+  if (packageJsonContent !== null) {
+    const packageJson = JSON.parse(stripByteOrderMark(packageJsonContent))
+    const packageManager = getPackageManagerFromPackageJson(packageJson)
+
+    if (packageManager) {
+      return packageManager
+    }
+  }
+
+  const lockFileChecks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['package-lock.json', 'npm'],
+    ['npm-shrinkwrap.json', 'npm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+  ]
+
+  for (const [filename, packageManager] of lockFileChecks) {
+    if (await fileExists(path.join(rootDir, filename))) {
+      return packageManager
+    }
+  }
+
+  return getPackageManagerFromUserAgent() ?? 'npm'
+}
+
+export function formatScriptCommand(packageManager, scriptName, args = []) {
+  const extraArgs = args.length > 0 ? args.join(' ') : ''
+
+  if (packageManager === 'npm') {
+    return `npm run ${scriptName}${extraArgs ? ` -- ${extraArgs}` : ''}`
+  }
+
+  if (packageManager === 'yarn') {
+    return `yarn ${scriptName}${extraArgs ? ` ${extraArgs}` : ''}`
+  }
+
+  if (packageManager === 'bun') {
+    return `bun run ${scriptName}${extraArgs ? ` ${extraArgs}` : ''}`
+  }
+
+  return `pnpm ${scriptName}${extraArgs ? ` -- ${extraArgs}` : ''}`
+}
+
+function formatPowerShellPnpmCommand(command) {
+  return command.replace(/^pnpm /u, 'pnpm.cmd ')
+}
+
+export async function printInstallResult(result, options = {}) {
+  const packageManager = options.packageManager ?? (await detectPackageManager(result.targetDir))
+
   if (result.updatedFiles.length === 0 && result.createdFiles.length === 0) {
     process.stderr.write(`ACE pack is already up to date in ${result.targetDir}\n`)
   }
@@ -248,14 +454,62 @@ export function printInstallResult(result) {
     process.stderr.write(`Created: ${result.createdFiles.join(', ')}\n`)
   }
 
-  process.stderr.write('Next: run pnpm.cmd ace:onboard\n')
+  if (result.onboarding?.applied) {
+    process.stderr.write(`Onboarded: ${result.onboarding.writtenFiles.join(', ')}\n`)
+  }
+
+  const nextCommands = []
+
+  if (!result.onboarding?.applied) {
+    nextCommands.push(formatScriptCommand(packageManager, 'ace:onboard', ['--apply']))
+  }
+
+  nextCommands.push(formatScriptCommand(packageManager, 'ace:check'))
+  nextCommands.push(formatScriptCommand(packageManager, 'ace:hub'))
+
+  process.stderr.write('\nNext:\n')
+
+  for (const command of nextCommands) {
+    process.stderr.write(`  ${command}\n`)
+  }
+
+  if (packageManager === 'pnpm' && process.platform === 'win32') {
+    process.stderr.write(
+      `\nWindows PowerShell note: if pnpm is blocked, use ${formatPowerShellPnpmCommand(
+        nextCommands[0],
+      )}\n`,
+    )
+  }
+}
+
+export async function runInstallCli(args, options = {}) {
+  const commandName = options.commandName ?? 'ace-pack'
+  const parsedArgs = parseInstallArgs(args)
+
+  if (parsedArgs.help) {
+    process.stdout.write(getHelpText(commandName))
+    return
+  }
+
+  const result = await installAcePack(parsedArgs.targetDir)
+
+  if (parsedArgs.apply) {
+    result.onboarding = await onboardRepository(parsedArgs.targetDir, {
+      apply: true,
+      preset: parsedArgs.preset ?? undefined,
+    })
+  }
+
+  await printInstallResult(result)
 }
 
 const isMainModule =
   process.argv[1] !== undefined && path.resolve(process.argv[1]) === currentFilePath
 
 if (isMainModule) {
-  const targetDir = resolveTargetDir(process.argv.slice(2))
-  const result = await installAcePack(targetDir)
-  printInstallResult(result)
+  await runInstallCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error)
+    process.stderr.write(`${message}\n\nRun ace-pack --help for usage.\n`)
+    process.exit(1)
+  })
 }

package/install-agent-memory-pack.mjs

@@ -2,7 +2,7 @@
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { installAcePack, printInstallResult, resolveTargetDir } from './install-ace-pack.mjs'
+import { installAcePack, runInstallCli } from './install-ace-pack.mjs'
 
 export const installAgentMemoryPack = installAcePack
 
@@ -11,7 +11,11 @@ const isMainModule =
   process.argv[1] !== undefined && path.resolve(process.argv[1]) === currentFilePath
 
 if (isMainModule) {
-  const targetDir = resolveTargetDir(process.argv.slice(2))
-  const result = await installAcePack(targetDir)
-  printInstallResult(result)
+  await runInstallCli(process.argv.slice(2), { commandName: 'agent-memory-pack' }).catch(
+    (error) => {
+      const message = error instanceof Error ? error.message : String(error)
+      process.stderr.write(`${message}\n\nRun agent-memory-pack --help for usage.\n`)
+      process.exit(1)
+    },
+  )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ace-pack",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-dependency cognitive architecture framework for AI-driven development.",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "install:pack": "node ./install-ace-pack.mjs",
     "install:legacy": "node ./install-agent-memory-pack.mjs",
     "link:global": "pnpm link --global",
+    "ace:validate": "node ./scripts/check-agent-memory.mjs",
     "test": "vitest run"
   },
   "devDependencies": {

package/scripts/agent-memory-templates.mjs

@@ -177,6 +177,9 @@ task.
 - Use \`pnpm ace:classify\` to select the adaptive task tier.
 - Run \`pnpm ace:onboard\` after fresh installation in an unfamiliar project
   before trusting project-specific risk rules.
+- On Windows PowerShell, use \`pnpm.cmd ace:classify\`,
+  \`pnpm.cmd ace:validate\`, and similar commands if script execution policy
+  blocks the \`pnpm\` shim.
 - For large or high-risk standard tasks, complete \`.ai/current-task.md\`
   Business Value and Technical Approach before writing code.
 - Treat \`.ai/*\` as the current source of task context and handoff state.
@@ -218,6 +221,10 @@ Before starting work:
 7. Read \`.ai/work-log.md\` only when you need extra historical context.
 8. If the memory files are missing, run \`pnpm ace:init\`.
 
+Command note: examples use \`pnpm\`. On Windows PowerShell, use
+\`pnpm.cmd ace:classify\`, \`pnpm.cmd ace:validate\`, and similar commands if
+the \`pnpm\` shim is blocked by execution policy.
+
 Legacy commands such as \`pnpm ai:task:classify\`, \`pnpm ai:task:finish\`,
 and \`pnpm agent-memory:init\` remain supported for compatibility.