fix: rebrand internal .aiox-core/package.json + add namespace drift gate (#739 Bug 2)

[rafaelscosta]

Closes Bug 2 from issue #739 (@gabrielolio's follow-up comment): the internal .aiox-core/package.json manifest was still declaring the legacy @aiox-fullstack/core@4.31.1 namespace while the surface package moved to @aiox-squads/core@5.x long ago.

Root cause

@aiox-fullstack/core → @aiox-squads/core rebrand swept the root package.json and most surfaces but skipped the internal .aiox-core/package.json. The drift went undetected because no pre-publish check looked at this internal file, and it ships inside every release of @aiox-squads/core. Operators investigating upgrade issues saw the legacy name surface in aiox info chains and other tooling that reads this file.

Changes

.aiox-core/package.json

• name: @aiox-fullstack/core → @aiox-squads/core-internal (the -internal suffix + private: true make it explicit this is NOT a separately-published package — it ships inside the parent surface)
• version: 4.31.1 → 5.2.6 (tracks parent surface)
• private: true defensively prevents accidental separate publish
• Dropped peerDependencies block (all four @aiox-fullstack/* peers referenced packages that don't exist)
• Dropped publish-only fields irrelevant to an internal manifest (module, types, bin, files, exports, publishConfig)
• Retained runtime dependencies consumed by .aiox-core/development/scripts/

New pre-publish gate

scripts/validate-aiox-core-namespace.js enforces five rules: file exists, name ends with -internal, private: true, version matches root, no @aiox-fullstack/* peers re-introduced.

Wired into validate:publish (which prepublishOnly chains), so future drift is blocked before release.

Why -internal suffix instead of just @aiox-squads/core

Two packages with the same name on the same npm registry — even with private: true — confuses tooling that resolves by name (the installer itself, lockfile resolution, npm ls, dependency graphs). The suffix is defensive disambiguation.

Test plan

• node scripts/validate-aiox-core-namespace.js → PASS
• npm run validate:publish → all 5 checks PASS (including new Check 5)
• No drift introduced in root package.json / no version mismatch
• After merge: students hitting the legacy namespace in .aiox-core/package.json pick up the corrected file via next aiox install --update (or any flow calling applyUpgrade(..., { includeModified: true }))

Related

• Original issue: [Bug]: --ci --yes ignorado no prompt de merge do CLAUDE.md durante install (v5.2.5) #739 (Bug 2 in the follow-up comment)
• Bug 1 from the same issue (--ci --yes ignored at CLAUDE.md merge prompt) is NOT addressed here — separate scope, needs markdown-merger.js refactor.
• Companion docs: this completes the namespace migration started in 61991a35 (rebrand aios → aiox commit) — that PR rebranded surfaces but missed the internal manifest.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores

  • Internal core package re-scoped and version bumped to 5.2.6 and marked private.
  • Manifest metadata and recorded hashes updated.
  • Added a new pre-publish validation command to repository scripts.

• Bug Fixes

  • Publish gating strengthened so namespace/version validation now blocks publishes on failure.

• Documentation

  • Added a non-negotiable release procedure section to DevOps agent guidelines and related docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aiox-core	Ready	Preview, Comment	May 17, 2026 1:49pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: dd6f8a7b-4916-41eb-94d1-832ccfb7232e

📥 Commits

Reviewing files that changed from the base of the PR and between 7d4fd5e and 1f4cb2b.

📒 Files selected for processing (4)

• .claude/skills/AIOX/agents/devops/SKILL.md
• .codex/agents/devops.md
• .gemini/rules/AIOX/agents/devops.md
• .kimi/skills/aiox-devops/SKILL.md

---

Walkthrough

Rescopes and simplifies .aiox-core/package.json to @aiox-squads/core-internal v5.2.6 (private), updates install-manifest hashes/timestamp, adds scripts/validate-aiox-core-namespace.js to enforce name/version/peerDependency rules, and wires the validator into the publish gate and root npm scripts.

Changes

Internal Package Namespace Migration

Layer / File(s)	Summary
Namespace validator script scripts/validate-aiox-core-namespace.js	New Node CLI validator that enforces .aiox-core/package.json name starts with @aiox-squads/ and ends with -internal, private: true, version equality with root, and rejects @aiox-fullstack/* peerDependencies. Exits 0 on pass, 1 on fail.
Publish gate and npm script bin/utils/validate-publish.js, package.json	Validator is executed from the publish gate via execFileSync('node', ...); missing or failing validator sets passed = false and blocks publish. Root package.json adds validate:aiox-core-namespace script.
Internal package restructuring .aiox-core/package.json	Package renamed to @aiox-squads/core-internal, version set to 5.2.6, private: true added; test script replaced; peerDependencies/peerDependenciesMeta, publishConfig, and exports removed; metadata updated.
Install manifest hash updates .aiox-core/install-manifest.yaml	Refreshes generated_at timestamp and updates recorded SHA256 hashes and sizes for data/entity-registry.yaml and the package.json entry (type remains other).
Release procedure documentation .claude/..., .codex/..., .gemini/..., .kimi/...	Adds a non-negotiable release SOP reference to DevOps agent guideline files directing agents to docs/guides/release-procedure.md and listing SOP constraints for tagging/publishing flows.

Sequence Diagram(s)

sequenceDiagram
  participant NPM as npm publish
  participant PublishGate as bin/utils/validate-publish.js
  participant Validator as scripts/validate-aiox-core-namespace.js
  participant RootPkg as root package.json
  participant InternalPkg as .aiox-core/package.json
  NPM->>PublishGate: invoke publish validations
  PublishGate->>Validator: execFileSync('node', [validatorPath])
  Validator->>RootPkg: read version
  Validator->>InternalPkg: read name, version, private, peerDependencies
  Validator->>PublishGate: exit 0 or exit 1 (PASS/FAIL)
  PublishGate->>NPM: allow or block publish

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area: devops, area: core

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: rebranding the internal .aiox-core/package.json and adding a namespace drift validation gate, directly matching the PR's primary objectives.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/aiox-core-internal-package-json

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

---

Generated by PR Automation (Story 6.1)

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

bin/utils/validate-publish.js (1)

141-146: ⚡ Quick win

Use execFileSync instead of shell-based execSync for both validator calls.

Lines 119 and 141 use shell string interpolation for node script paths. While these specific paths are hardcoded and low-risk, it's better practice to use execFileSync('node', [path], ...) to avoid shell parsing entirely.

Suggested change

-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
@@
   const depValidatorPath = path.join(PROJECT_ROOT, 'scripts', 'validate-aiox-core-deps.js');
   if (fs.existsSync(depValidatorPath)) {
-    execSync(`node "${depValidatorPath}"`, {
+    execFileSync('node', [depValidatorPath], {
       encoding: 'utf8',
       cwd: PROJECT_ROOT,
       timeout: 30000,
       stdio: 'inherit',
     });
@@
   const nsValidatorPath = path.join(PROJECT_ROOT, 'scripts', 'validate-aiox-core-namespace.js');
   if (fs.existsSync(nsValidatorPath)) {
-    execSync(`node "${nsValidatorPath}"`, {
+    execFileSync('node', [nsValidatorPath], {
       encoding: 'utf8',
       cwd: PROJECT_ROOT,
       timeout: 10000,
       stdio: 'inherit',
     });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bin/utils/validate-publish.js` around lines 141 - 146, Replace the
shell-based execSync calls that invoke node with execFileSync to avoid shell
parsing: locate the execSync invocations that pass a string like `node
"${nsValidatorPath}"` (and the earlier validator call at line ~119 that uses the
other validator path variable) and switch to calling execFileSync('node',
[nsValidatorPath], options) (and similarly for the other validator variable).
Keep the same options object (encoding, cwd, timeout, stdio) but pass them to
execFileSync; ensure you import/require execFileSync from child_process if not
already present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bin/utils/validate-publish.js`:
- Around line 140-149: The current guard around nsValidatorPath silently skips
the namespace validator when the file is missing; change this to fail-closed by
replacing the else branch so it aborts the publish with a non-zero exit (e.g.,
throw new Error or process.exit(1)) and a clear message that the validator
script at nsValidatorPath is required; ensure the block around execSync still
runs the validator via execSync(...) and that any thrown errors from execSync
propagate (or are caught and rethrown) so publishing cannot continue on missing
or failing namespace validation.

In `@scripts/validate-aiox-core-namespace.js`:
- Around line 57-62: The check currently only verifies
internal.name.endsWith('-internal'), allowing wrong scopes; update the
validation to require the correct npm scope as well (e.g.
internal.name.startsWith('`@aiox-core/`')) and ensure both conditions are true
before passing; modify the conditional around internal.name and the fail(...)
message to reflect and enforce that internal.name both begins with the target
scope (use the scope string used by this repo) and endsWith('-internal') so
names like '`@any-scope/foo-internal`' no longer pass.

---

Nitpick comments:
In `@bin/utils/validate-publish.js`:
- Around line 141-146: Replace the shell-based execSync calls that invoke node
with execFileSync to avoid shell parsing: locate the execSync invocations that
pass a string like `node "${nsValidatorPath}"` (and the earlier validator call
at line ~119 that uses the other validator path variable) and switch to calling
execFileSync('node', [nsValidatorPath], options) (and similarly for the other
validator variable). Keep the same options object (encoding, cwd, timeout,
stdio) but pass them to execFileSync; ensure you import/require execFileSync
from child_process if not already present.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4655faac-8451-40c5-8d8a-f43194d9dc82

📥 Commits

Reviewing files that changed from the base of the PR and between 342ef63 and edda142.

📒 Files selected for processing (5)

• .aiox-core/install-manifest.yaml
• .aiox-core/package.json
• bin/utils/validate-publish.js
• package.json
• scripts/validate-aiox-core-namespace.js

Addressed in 7d4fd5e. (1) Switched both validator invocations from execSync(shell-string) to execFileSync(node, [path]). (2) Fail-closed when validate-aiox-core-namespace.js is missing (was silently SKIP — exactly the pattern that allowed the original drift). (3) Added @aiox-squads/ scope startsWith check before the -internal suffix check so @any-scope/foo-internal no longer passes. Also regenerated install-manifest.yaml — CI was failing on stale hash.

[coderabbitai]

🧹 Nitpick comments (1)

bin/utils/validate-publish.js (1)

148-160: 💤 Low value

Add a PASS message after successful namespace validation for consistency.

Check 4 (dependency completeness) prints PASS: .aiox-core dependency completeness validated after the validator succeeds (line 125), but Check 5 does not print a corresponding PASS message. This makes the gate output inconsistent and less clear when debugging successful runs.

Suggested fix

   try {
     execFileSync('node', [nsValidatorPath], {
       encoding: 'utf8',
       cwd: PROJECT_ROOT,
       timeout: 10000,
       stdio: 'inherit',
     });
+    console.log('PASS: .aiox-core/package.json namespace/version sync validated');
   } catch (_nsErr) {
     console.error('FAIL: .aiox-core/package.json namespace/version drift detected');
     console.error('  Fix: Run "node scripts/validate-aiox-core-namespace.js" to see details');
     passed = false;
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bin/utils/validate-publish.js` around lines 148 - 160, The namespace/version
validator block currently only logs failure; after the successful execFileSync
call (the try branch that runs node with nsValidatorPath), add a success log
consistent with Check 4 — e.g., call console.log('PASS: .aiox-core
namespace/version validated') and ensure the existing passed variable remains
true; locate the execFileSync invocation that references nsValidatorPath and
insert the PASS message immediately after it so Check 5 prints a success line on
successful validation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@bin/utils/validate-publish.js`:
- Around line 148-160: The namespace/version validator block currently only logs
failure; after the successful execFileSync call (the try branch that runs node
with nsValidatorPath), add a success log consistent with Check 4 — e.g., call
console.log('PASS: .aiox-core namespace/version validated') and ensure the
existing passed variable remains true; locate the execFileSync invocation that
references nsValidatorPath and insert the PASS message immediately after it so
Check 5 prints a success line on successful validation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 29d96dbc-6f49-431a-90c0-f80ab541232c

📥 Commits

Reviewing files that changed from the base of the PR and between edda142 and 7d4fd5e.

📒 Files selected for processing (3)

• .aiox-core/install-manifest.yaml
• bin/utils/validate-publish.js
• scripts/validate-aiox-core-namespace.js

✅ Files skipped from review due to trivial changes (1)

• .aiox-core/install-manifest.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/validate-aiox-core-namespace.js