@aetheros/specs 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hariprasath Thanarajah
+
+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/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@aetheros/specs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abigshana/AetherOS.git",
+    "directory": "packages/specs"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "check": "node --check src/index.js && node --check src/approval.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin",
+    "templates",
+    "kits",
+    "README.md"
+  ]
+}

package/src/approval.js

@@ -0,0 +1,131 @@
+import {createHash, randomBytes} from 'node:crypto';
+import {existsSync, lstatSync, realpathSync, statSync, openSync, closeSync, fsyncSync, rmSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync} from 'node:fs';
+import {basename, dirname, join, relative, resolve, sep} from 'node:path';
+import {evaluateSpecGate, getSpecArtifacts, validateSpecPath} from './index.js';
+
+/** AetherOS keeps its approval records in .aether/specs/; the spec files themselves are only read here, never changed. */
+export const RECORDS_DIR = '.aether/specs';
+export const APPROVED_FILES = Object.freeze(['spec.md', 'plan.md', 'tasks.md']);
+
+const text = v => typeof v === 'string' && v.trim().length > 0;
+const posix = p => p.split(sep).join('/');
+const hashFile = file => createHash('sha256').update(readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex');
+
+// Resolve the nearest existing ancestor so missing record directories cannot hide an escaping symlink.
+function contained(base, target) {
+  const path = resolve(base, target);
+  const lexical = relative(base, path);
+  if (lexical === '..' || lexical.startsWith('..' + sep) || lexical.startsWith(sep)) throw new Error('Path must remain within project root');
+  let ancestor = path;
+  while (!lstatSync(ancestor, {throwIfNoEntry: false})) ancestor = dirname(ancestor);
+  const actual = relative(realpathSync(base), realpathSync(ancestor));
+  if (actual === '..' || actual.startsWith('..' + sep) || actual.startsWith(sep)) throw new Error('Path must remain within project root');
+  return path;
+}
+
+function locate(root, specPath) {
+  const base = resolve(root);
+  const dir = validateSpecPath(base, specPath);
+  const spec = posix(relative(base, dir));
+  return {base, dir, spec, record: contained(base, join(RECORDS_DIR, basename(dir) + '.json'))};
+}
+
+function readRecord(file, spec) {
+  if (!existsSync(file)) return {schemaVersion: 1, spec};
+  const value = JSON.parse(readFileSync(file, 'utf8'));
+  if (!value || value.schemaVersion !== 1 || value.spec !== spec) throw new Error('Invalid spec record: ' + posix(file));
+  return value;
+}
+
+function writeRecord(file, value) {
+  mkdirSync(dirname(file), {recursive: true});
+  const temp = file + '.' + randomBytes(12).toString('hex') + '.tmp';
+  let created = false;
+  try {
+    const handle = openSync(temp, 'wx', 0o600); created = true;
+    try { writeFileSync(handle, JSON.stringify(value, null, 2) + '\n'); fsyncSync(handle); } finally { closeSync(handle); }
+    renameSync(temp, file);
+  } finally { if (created) rmSync(temp, {force: true}); }
+}
+
+/** Link a spec folder (specs/<feature>) to a project feature folder and/or a GitHub issue. Keeps any approval. */
+export function linkSpec(root, specPath, {feature, issue} = {}) {
+  const {base, spec, record} = locate(root, specPath);
+  const value = readRecord(record, spec);
+  if (feature !== undefined) {
+    if (!text(feature) || !existsSync(resolve(base, feature))) throw new Error('Feature folder does not exist: ' + feature);
+    const folder = contained(base, feature);
+    if (!statSync(folder).isDirectory()) throw new Error('Feature folder must be a directory');
+    value.feature = posix(relative(base, folder));
+  }
+  if (issue !== undefined) {
+    if (!Number.isSafeInteger(issue) || issue < 1) throw new Error('Issue must be a positive number');
+    value.issue = issue;
+  }
+  writeRecord(record, value);
+  return value;
+}
+
+/**
+ * Record a human approval bound to the current content of spec.md, plan.md and tasks.md. Any later change to those
+ * files makes the approval stale. The approver name is recorded as given: hosts must verify who is approving.
+ */
+export function approveSpec(root, specPath, {approver, now = () => new Date().toISOString()} = {}) {
+  if (!text(approver)) throw new Error('An approver is required');
+  const {dir, spec, record} = locate(root, specPath);
+  const gate = evaluateSpecGate(getSpecArtifacts(root, specPath));
+  if (!gate.ready) throw new Error('Spec is not ready for approval; missing ' + gate.missing.join(', '));
+  const value = readRecord(record, spec);
+  value.approval = {by: approver.trim(), at: now(), hashes: Object.fromEntries(APPROVED_FILES.map(f => [f, hashFile(join(dir, f))]))};
+  writeRecord(record, value);
+  return value;
+}
+
+/** Artifacts, readiness, approval and staleness for one spec. */
+export function specStatus(root, specPath) {
+  const {dir, spec, record} = locate(root, specPath);
+  const artifacts = getSpecArtifacts(root, specPath);
+  const gate = evaluateSpecGate(artifacts);
+  const value = readRecord(record, spec);
+  const approval = value.approval;
+  const changed = approval ? APPROVED_FILES.filter(f => !existsSync(join(dir, f)) || hashFile(join(dir, f)) !== approval.hashes?.[f]) : [];
+  return {
+    spec, artifacts, ready: gate.ready, missing: gate.missing,
+    approved: Boolean(approval) && changed.length === 0, stale: Boolean(approval) && changed.length > 0, changed,
+    ...(approval && {approvedBy: approval.by, approvedAt: approval.at}),
+    ...(value.feature && {feature: value.feature}), ...(value.issue && {issue: value.issue})
+  };
+}
+
+/** Status of every directory under specs/. */
+export function listSpecs(root) {
+  const specs = join(resolve(root), 'specs');
+  if (!existsSync(specs)) return [];
+  return readdirSync(specs, {withFileTypes: true}).filter(e => e.isDirectory()).map(e => e.name).sort().map(name => specStatus(root, 'specs/' + name));
+}
+
+/** Code may start only when the spec is complete and approved for its current content. */
+export function evaluateApprovedSpecGate(root, specPath) {
+  const status = specStatus(root, specPath);
+  const reasons = [];
+  if (!status.ready) reasons.push('missing ' + status.missing.join(', '));
+  if (status.stale) reasons.push('changed since approval: ' + status.changed.join(', '));
+  else if (!status.approved) reasons.push('not approved');
+  return {ok: reasons.length === 0, reasons, status};
+}
+
+/** Records pointing at specs or feature folders that no longer exist. */
+export function checkSpecRecords(root) {
+  const base = resolve(root);
+  const dir = join(base, RECORDS_DIR);
+  const problems = [];
+  if (!existsSync(dir)) return {ok: true, problems};
+  try { contained(base, dir); } catch { return {ok: false, problems: ['Spec records must remain within project root']}; }
+  for (const file of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+    let value;
+    try { value = JSON.parse(readFileSync(contained(base, join(dir, file)), 'utf8')); } catch { problems.push(`${RECORDS_DIR}/${file}: not valid JSON`); continue; }
+    if (!text(value?.spec) || !existsSync(join(base, value.spec))) problems.push(`${RECORDS_DIR}/${file}: spec ${value?.spec} does not exist`);
+    if (value?.feature && !existsSync(join(base, value.feature))) problems.push(`${RECORDS_DIR}/${file}: feature folder ${value.feature} does not exist`);
+  }
+  return {ok: problems.length === 0, problems};
+}

package/src/index.js

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readdirSync, statSync, realpathSync, writeFileSync } from 'node:fs';
+import { resolve, relative, sep } from 'node:path';
+const markers = ['specs', '.aether/principles.md'];
+/** What a project has: a specs/ folder (one folder per feature) and, optionally, its written principles in .aether/principles.md. */
+export function detectSpecs(root) {
+  const base = resolve(root);
+  const found = markers.filter(path => existsSync(resolve(base,path)));
+  return {present: found.includes('specs'), found, principles:found.includes('.aether/principles.md')};
+}
+export function validateSpecPath(root, specPath) {
+  const base=resolve(root);
+  const path=resolve(base,specPath);
+  const rel=relative(base,path);
+  if (rel==='..' || rel.startsWith('..'+sep) || rel.startsWith(sep)) throw new Error('Spec path must remain within project root');
+  if (!rel.startsWith('specs'+sep) && rel!=='specs') throw new Error('Specifications must be located in specs/');
+  if (!existsSync(path) || !statSync(path).isDirectory()) throw new Error('Specification directory does not exist');
+  const realRoot=realpathSync(base), realPath=realpathSync(path);
+  const realRel=relative(realRoot,realPath);
+  if(realRel==='..'||realRel.startsWith('..'+sep)||realRel.startsWith(sep)) throw new Error('Spec path must remain within project root');
+  return path;
+}
+export function getSpecArtifacts(root, specPath) {
+  const path=validateSpecPath(root,specPath);
+  return Object.fromEntries(['spec.md','plan.md','tasks.md','research.md','data-model.md'].map(name=>[name,artifactExists(root,path,name)]));
+}
+export function evaluateSpecGate(artifacts,{requireTasks=true}={}) {
+  const missing=['spec.md','plan.md',...(requireTasks?['tasks.md']:[])].filter(name=>!artifacts[name]);
+  return {ready:missing.length===0,missing};
+}
+
+
+function artifactExists(root,path,name) {
+  const file=resolve(path,name);
+  if(!existsSync(file)) return false;
+  const rel=relative(realpathSync(root),realpathSync(file));
+  if(rel==='..'||rel.startsWith('..'+sep)||rel.startsWith(sep)) throw new Error('Spec artifact must remain within project root');
+  return statSync(file).isFile();
+}
+export {APPROVED_FILES, RECORDS_DIR, approveSpec, checkSpecRecords, evaluateApprovedSpecGate, linkSpec, listSpecs, specStatus} from './approval.js';
+
+const TEMPLATES = {
+  'spec.md': name => `# ${name}
+
+## Goal
+One or two sentences: what this is for and who it helps.
+
+## Requirements
+- What must be true when it is done, one line each.
+
+## Out of scope
+- What this deliberately does not do.
+
+## Open questions
+- Anything that must be answered before building.
+`,
+  'plan.md': name => `# Plan: ${name}
+
+## Approach
+How it will be built, in plain words.
+
+## Steps
+1. The first small step.
+
+## Risks
+- What could go wrong and how it will be noticed.
+`,
+  'tasks.md': name => `# Tasks: ${name}
+
+- [ ] First task
+`
+};
+/** Create specs/NNN-<name>/ with spec.md, plan.md and tasks.md to fill in. Never replaces an existing folder. Returns the folder (project-relative). */
+export function createSpec(root, name) {
+  const base = resolve(root);
+  const slug = String(name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50);
+  if (!slug) throw new Error('Give the feature a short name, like: aether spec new search-filters');
+  const specs = resolve(base, 'specs');
+  mkdirSync(specs, {recursive: true});
+  const realSpecs = realpathSync(specs), rel = relative(realpathSync(base), realSpecs);
+  if (rel !== 'specs') throw new Error('specs/ must be a real folder inside the project');
+  const taken = readdirSync(specs).map(n => /^(\d{3})-/.exec(n)?.[1]).filter(Boolean).map(Number);
+  const number = String((taken.length ? Math.max(...taken) : 0) + 1).padStart(3, '0');
+  const dir = resolve(specs, `${number}-${slug}`);
+  mkdirSync(dir);
+  for (const [file, template] of Object.entries(TEMPLATES)) writeFileSync(resolve(dir, file), template(slug.replace(/-/g, ' ')), {flag: 'wx'});
+  return `specs/${number}-${slug}`;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.