@aqaf/cli 0.0.0-stage → 1.1.0

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,44 @@
-# Temporary Holding Version
+# @aqaf/cli — npm distribution (release candidate / not published)
 
-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.0.tgz
+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`. Package name `@aqaf/cli` is provisional, requires ownership of npm scope. Publish only after name availability, license, package integrity, CI and authority checks.
+
+## 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.

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,32 @@
+'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 || {}), 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);
+  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,52 @@
 {
   "name": "@aqaf/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "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/",
+    "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.0'

package/vendor/aqaf/__main__.py

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