@aqaf/cli 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AQAF contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @aqaf/cli — published npm distribution
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package exposes the **same Python AQAF analyzer** to JS/TS projects, not a second independent scoring implementation. Requires **Node 18+ and Python 3.9+**. No `postinstall` scripts, network calls or execution of target project code. Never run the analyzer on an untrusted repository via arbitrary user hooks: AQAF only reads data.
+
+```bash
+npm install @aqaf/cli@1.1.1
+npx aqaf . --format json
+```
+
+Programmatic Node API:
+
+```js
+const { scan } = require('@aqaf/cli');
+const report = scan(process.cwd(), { pack: 'web', profile: 'npm_library' });
+console.log(report.findings);
+```
+
+For a Windows terminal with multiple Python installations set `AQAF_PYTHON`. The public package is https://www.npmjs.com/package/@aqaf/cli The 1.1.1 release includes project discovery, scope filtering, optional documentation and book-informed reviews. See the release evidence for channel installation verification. The hosted cross-platform matrix remains pending; do not infer those results from this local check. For a global CLI use `npm install --global @aqaf/cli@1.1.1`. Further publication requires owner approval.
+
+## Owner release preparation
+
+The candidate declares public access and the npm registry in `publishConfig`.
+This is configuration, not proof of scope ownership or publication. Repository,
+issue tracker and homepage metadata point to the AQAF project.
+
+Build with fresh canonical Python files (Python 3.11+ and npm required):
+
+```sh
+python3 support/aqaf-build/scripts/aqaf_release.py --repo . verify
+python3 support/aqaf-build/scripts/aqaf_release.py --repo . build --targets npm --out /tmp/aqaf-npm-candidate
+```
+
+Run these commands from the owner repository root with a fresh external output
+directory. The helper writes a tarball, checksums and provenance without
+publishing. Test the exact tarball in an isolated consumer before release.
+Owner tasks and approval gates live in `.tasks/001-npm-preparation.md`,
+`.tasks/002-npm-publication.md` and `.tasks/003-chocolatey-release.md`.
+
+`make npm-build PYTHON=python3 NPM_OUT=/tmp/aqaf-npm-candidate` additionally runs
+the packaged-consumer validator from `scripts/release/check_npm_candidate.py`.
+To recheck an existing trusted candidate, pass its exact `.tgz` path to that
+script. It never uploads and does not need npm registry credentials. The active
+build-only npm candidate workflow tests Linux/macOS/Windows with Node 18/24 and
+Python 3.9/3.12; configuration alone is not proof those jobs have passed.
+
+## Experimental review option (unreleased 1.2.0)
+
+Use `scan(repo, {reviewSignals: true})` or CLI `--review-signals` for bounded JS/TS
+review observations. `reviewSignals` must be boolean. The separate `review` result
+is experimental, unreviewed and unscored; normal findings, scores and baseline
+gates are unchanged. Default calls omit it. No target code or credential decoding
+is performed. This source candidate has not been published.
+
+Source candidate 1.3.0 respects `.gitignore` by default. Use
+`scan(repo, {respectGitignore: false})` for an explicit opt-out. Candidate scope
+options include `scopePolicy`, `scopeConfig`, `inventoryAll`, `component`,
+`reviewMaxFiles`, `reviewMaxBytes`, `reviewFileBytes`, `reviewOffset`,
+`reviewCursorIn` and `reviewCursorOut`. `reviewSignals` remains opt-in and unscored.
+The archive includes only Python/JSON runtime files; bytecode caches are excluded.
+
+The bundled Python runtime also supports `aqaf projects discover ROOT`, the opt-in local `projects` catalogue commands, and `aqaf docs check ROOT`. Use `invoke(['projects', 'discover', root])` from the Node API for additive commands. Discovery and documentation checks never execute target code; catalogue storage uses Python's standard-library SQLite. Experimental probabilities and observations are uncalibrated and unscored.
+
+Add `--review-knowledge` to an assessment for the optional book-informed human review agenda. It uses 31 attributed secondary notes and leaves questions unknown until reviewed; it does not change scores or run target checks.

package/bin/aqaf.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+const { invoke } = require('../index');
+try {
+  const result = invoke(process.argv.slice(2));
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.status == null ? 1 : result.status;
+} catch (error) {
+  console.error('AQAF:', error.message);
+  process.exitCode = 1;
+}

package/index.js

@@ -0,0 +1,51 @@
+'use strict';
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const vendor = path.join(__dirname, 'vendor');
+
+function invoke(args, opts = {}) {
+  if (!Array.isArray(args) || args.some(v => typeof v !== 'string')) throw new TypeError('args must be an array of strings');
+  const pythonCandidates = opts.python ? [opts.python] : process.env.AQAF_PYTHON ? [process.env.AQAF_PYTHON] : (process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3','python']);
+  for (const command of pythonCandidates) {
+    const pre = command === 'py' ? ['-3'] : [];
+    const env = { ...process.env, ...(opts.env || {}), PYTHONDONTWRITEBYTECODE: '1', PYTHONPATH: [vendor, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter) };
+    const result = spawnSync(command, [...pre, '-m', 'aqaf', ...args], {
+      cwd: opts.cwd || process.cwd(), env, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+      stdio: opts.stdio || 'pipe', windowsHide: true
+    });
+    if (result.error && result.error.code === 'ENOENT') continue;
+    if (result.error) throw result.error;
+    return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+  }
+  throw new Error('AQAF npm distribution requires Python 3.9+ on PATH. Set AQAF_PYTHON to an absolute Python executable.');
+}
+function scan(repo, options = {}) {
+  const argv = [repo, '--format', 'json', '--output', '-'];
+  if (options.profile) argv.push('--profile', options.profile);
+  if (options.pack) argv.push('--pack', options.pack);
+  if (options.reviewSignals !== undefined && typeof options.reviewSignals !== 'boolean') throw new TypeError('reviewSignals must be boolean');
+  if (options.reviewSignals) argv.push('--review-signals');
+  for (const [name, flag] of [['respectGitignore','gitignore'],['inventoryAll','inventory-all']]) {
+    if (options[name] !== undefined && typeof options[name] !== 'boolean') throw new TypeError(`${name} must be boolean`);
+    if (options[name] === true) argv.push(`--${flag}`);
+    if (name === 'respectGitignore' && options[name] === false) argv.push('--no-gitignore');
+  }
+  for (const [name,flag] of [['scopePolicy','scope-policy'],['scopeConfig','scope-config'],['component','component'],['reviewCursorIn','review-cursor-in'],['reviewCursorOut','review-cursor-out']]) {
+    if (options[name] !== undefined) {
+      if (typeof options[name] !== 'string') throw new TypeError(`${name} must be a string`);
+      argv.push(`--${flag}`, options[name]);
+    }
+  }
+  for (const [name,flag] of [['reviewMaxFiles','review-max-files'],['reviewMaxBytes','review-max-bytes'],['reviewFileBytes','review-file-bytes'],['reviewOffset','review-offset']]) {
+    if (options[name] !== undefined) {
+      if (!Number.isSafeInteger(options[name]) || options[name] < (name === 'reviewOffset' ? 0 : 1)) throw new TypeError(`${name} must be a bounded integer`);
+      argv.push(`--${flag}`, String(options[name]));
+    }
+  }
+  for (const capability of (options.capabilities || [])) argv.push('--capability', capability);
+  if (options.profileDir) argv.push('--profile-dir', options.profileDir);
+  const result = invoke(argv, options);
+  if (result.status !== 0) throw new Error(`AQAF scan failed (${result.status}): ${result.stderr}`);
+  return JSON.parse(result.stdout);
+}
+module.exports = { invoke, scan };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@aqaf/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Local-first architecture assessment, Node.js distribution wrapper around the bundled AQAF Python engine",
+  "type": "commonjs",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "aqaf": "./bin/aqaf.js"
+  },
+  "files": [
+    "bin/",
+    "vendor/**/*.py",
+    "vendor/**/*.json",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "keywords": [
+    "architecture",
+    "codex",
+    "code-review",
+    "analysis",
+    "software-quality"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/focsd/aqaf.git",
+    "directory": "distribution/npm"
+  },
+  "homepage": "https://aqaf.focsd.com",
+  "bugs": {
+    "url": "https://github.com/focsd/aqaf/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/vendor/aqaf/__init__.py

@@ -0,0 +1,2 @@
+"""AQAF local, offline, heuristic architecture assessment."""
+__version__ = '1.1.1'

package/vendor/aqaf/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())