@parthiv-joshi-29/peos 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# PEOS
+
+> **Personal Engineering Operating System**
+
+## Quick start
+
+Install the CLI from this repository, then initialize a project:
+
+```bash
+npm install -g @parthiv-joshi-29/peos
+peos init ./my-project
+```
+
+Preview the files first with `peos init ./my-project --dry-run`.
+
+PEOS is a developer-first project foundation generator designed to help teams and solo developers initialize repeatable engineering environments with reusable documentation and standards.
+
+Instead of starting every project from scratch, PEOS captures the repeated decisions that usually happen at the beginning of development—such as folder structure, documentation, tooling, conventions, and project rules—and turns them into reusable workflows that can be executed with a single command.
+
+PEOS sits **before AI coding agents**. Its job is to prepare the project foundation so that coding agents can work inside a clear, consistent, and production-ready environment rather than guessing how the project should be structured.
+
+At its core, PEOS is about making engineering setup intentional, repeatable, and scalable.
+
+---
+
+# Why PEOS?
+
+Starting a new project usually means repeating the same engineering tasks over and over again:
+
+* Creating the folder structure
+* Choosing a technology stack
+* Configuring development tools
+* Writing project documentation
+* Defining coding and architectural standards
+* Initializing Git repositories
+* Preparing reusable templates for future work
+
+These tasks are important, but they are also repetitive and easy to overlook. When they are done inconsistently, the result is often a project that feels fragmented from the beginning.
+
+PEOS exists to solve that problem.
+
+It automates the initialization process while still allowing developers to customize workflows for different project types, teams, and goals. Instead of forcing every project into the same shape, PEOS helps create the right foundation for each one.
+
+The goal is not just to save time. The goal is to make the beginning of every project more deliberate, more consistent, and easier to build on.
+
+---
+
+# Core Philosophy
+
+PEOS is built around a few simple principles:
+
+* Engineering workflows should be reusable, not rewritten for every project.
+* Every project should begin with a solid foundation.
+* Developers should own their workflows and be able to adapt them to their needs.
+* AI coding agents should focus on writing software, not preparing projects.
+* Simplicity is better than unnecessary abstraction.
+* Good engineering decisions should be captured once and reused many times.
+
+PEOS is not meant to replace engineering judgment. It is meant to preserve it, package it, and make it easier to apply consistently across projects.
+
+---
+
+# Features
+
+## Workflow Engine
+
+PEOS provides a workflow engine for executing reusable engineering workflows that initialize projects in a structured way.
+
+A workflow can define how a project should be created, what files should be generated, what rules should be applied, and what documentation should be included. This makes it possible to standardize project setup without making it rigid.
+
+## Project Templates
+
+PEOS supports project templates that represent different kinds of engineering foundations.
+
+Templates are not just technology presets. They are project profiles that reflect the needs of different kinds of work.
+
+Examples include:
+
+* Production Application
+* Side Project
+* API Service
+* Library
+* CLI Tool
+
+Each template can define its own structure, documentation, rules, and setup behavior so that the project starts with the right assumptions from day one.
+
+## Rules Generation
+
+PEOS can generate project rule files before development begins.
+
+These rules help establish engineering standards and conventions such as:
+
+* Code style expectations
+* Architectural boundaries
+* Documentation requirements
+* Workflow preferences
+* AI agent behavior guidelines
+
+This is especially useful when working with AI coding agents, because it gives them a clear context for how the project should be handled.
+
+## Engineering Documentation
+
+PEOS can automatically initialize the documentation needed to guide a project from idea to implementation.
+
+This may include:
+
+* Vision
+* Product Requirements Document (PRD)
+* Architecture
+* Technical Specification
+* Development Plan
+* Changelog
+
+By generating these documents early, PEOS helps teams think through the project before implementation begins and keeps important decisions visible throughout development.
+
+## Technology Stack Configuration
+
+PEOS supports customization across different technologies and project preferences.
+
+This can include:
+
+* Frameworks
+* Databases
+* Package managers
+* Deployment targets
+* Runtime environments
+* Tooling preferences
+
+The goal is to make project initialization flexible enough to support different engineering styles while still keeping the setup process structured and repeatable.
+
+---
+
+# Planned CLI
+
+```bash
+peos init
+
+peos template list
+
+peos template show node-service
+
+peos template validate node-service
+
+peos context inspect
+
+peos doctor
+
+peos workflow
+
+peos template production-app
+
+peos template side-project
+
+peos rules
+
+peos doctor
+
+peos update
+```
+
+> Command names are subject to change during development.
+
+These commands are intended to make PEOS easy to use from the terminal while keeping the workflow focused on project initialization, configuration, and maintenance.
+
+---
+
+# Repository Structure
+
+```text
+peos/
+├── cli/
+├── docs/
+├── templates/
+├── workflows/
+├── examples/
+├── .github/
+├── README.md
+├── LICENSE
+├── CONTRIBUTING.md
+└── CHANGELOG.md
+```
+
+This structure reflects the main parts of the project:
+
+* `cli/` for command-line functionality
+* `docs/` for project documentation and engineering references
+* `templates/` for reusable project profiles
+* `workflows/` for initialization logic and automation steps
+* `examples/` for sample usage and reference implementations
+* `.github/` for repository automation and community files
+
+---
+
+# Roadmap
+
+### Milestone 1
+
+* Project foundation
+* Engineering documentation
+* Repository setup
+
+### Milestone 2
+
+* CLI bootstrap
+* Command parsing
+* Configuration loading
+
+### Milestone 3
+
+* Workflow engine
+
+### Milestone 4
+
+* Template engine
+
+### Milestone 5
+
+* Project generation
+
+### Milestone 6
+
+* Official workflows
+
+### Milestone 7
+
+* Public release
+
+The roadmap reflects the intended progression of PEOS from a documented vision into a usable engineering system. The early milestones focus on clarity and structure, while later milestones expand into automation, templates, and project generation.
+
+---
+
+# Status and limitations
+
+PEOS is an early V1 prototype. The working path is `peos init`, using one built-in `node-service` template. It generates a small TypeScript project, PEOS metadata, a manifest, and generic Markdown context.
+
+It does not yet execute workflows, run AI agents, update existing foundations, merge managed files, load remote assets, or support additional asset types. `peos update` and `peos diff` remain deferred until real projects establish safe generated-file ownership rules. See [the V1 decision](docs/decisions/0001-v1-boundary.md) and [the development plan](docs/development-plan.md).
+
+The future template direction is documented in [ADR 0002](docs/decisions/0002-user-owned-templates-and-harness-authoring.md): users own and customize their templates, while agentic harnesses may help create and validate them through PEOS interfaces.
+
+The immediate test is whether `peos init ./my-project` saves meaningful setup time and produces context developers keep after real work begins.
+
+---
+
+# Contributing
+
+Contributions, ideas, discussions, and feedback are welcome once the project reaches its first public release.
+
+PEOS is being built as a long-term engineering system, and community input will be valuable as the project grows. If you are interested in workflows, developer tooling, project automation, or AI-assisted engineering, your perspective will help shape the direction of the project.
+
+---
+
+# License
+
+This project will be released under the MIT License.

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const VERSION = "0.1.0";
+const interactive = Boolean(process.stdout.isTTY);
+const color = (code, value) => interactive ? `\x1b[${code}m${value}\x1b[0m` : value;
+const logo = () => [
+    color("38;5;75", "  ██████╗ ███████╗ ██████╗ ███████╗"),
+    color("38;5;111", "  ██╔══██╗██╔════╝██╔═══██╗██╔════╝"),
+    color("38;5;147", "  ██████╔╝█████╗  ██║   ██║███████╗"),
+    color("38;5;183", "  ██╔═══╝ ██╔══╝  ██║   ██║╚════██║"),
+    color("38;5;219", "  ██║     ███████╗╚██████╔╝███████║"),
+    color("38;5;225", "  ╚═╝     ╚══════╝ ╚═════╝ ╚══════╝")
+].join("\n");
+const step = (label, detail) => console.log(`  ${color("32", "✓")} ${label}${detail ? color("2", ` · ${detail}`) : ""}`);
+const TEMPLATE = { name: "node-service", version: "1.0.0", description: "A minimal TypeScript Node.js service foundation" };
+const templateFiles = ["README.md", "package.json", "tsconfig.json", "src/index.ts", ".peos/project.yaml", ".peos/generated/engineering-environment.md"];
+const projectName = (target) => path.basename(path.resolve(target)) || "project";
+const filesFor = (name) => [
+    ["README.md", `# ${name}\n\nInitialized with PEOS.\n\nRun \`npm install\` and \`npm test\` to verify the foundation.\n`],
+    ["package.json", JSON.stringify({ name, version: "0.1.0", private: true, type: "module", scripts: { build: "tsc", test: "npm run build && node dist/index.js" }, devDependencies: { typescript: "^5.0.0" } }, null, 2) + "\n"],
+    ["tsconfig.json", JSON.stringify({ compilerOptions: { target: "ES2022", module: "NodeNext", moduleResolution: "NodeNext", rootDir: "src", outDir: "dist", strict: true }, include: ["src/**/*.ts"] }, null, 2) + "\n"],
+    ["src/index.ts", `console.log("${name} is ready");\n`],
+    [".peos/project.yaml", `format_version: 1\nproject:\n  name: ${name}\ntemplate:\n  name: ${TEMPLATE.name}\n  version: ${TEMPLATE.version}\n  source: builtin\nharness:\n  target: generic-markdown\n`],
+    [".peos/generated/engineering-environment.md", `# PEOS Engineering Environment\n\n## Project\n\n- Name: ${name}\n- Template: ${TEMPLATE.name}@${TEMPLATE.version}\n\n## Boundary\n\nPEOS prepares the engineering environment. The developer or agentic harness performs the engineering work.\n\n## Documents\n\n- [Project README](../../README.md)\n- [Project metadata](../project.yaml)\n`]
+];
+function manifest(name, files) {
+    const entries = files.map(([file, content]) => `  - path: ${file}\n    sha256: ${crypto.createHash("sha256").update(content).digest("hex")}`).join("\n");
+    return `format_version: 1\ngenerated_by:\n  peos_version: ${VERSION}\n  operation: init\nproject:\n  name: ${name}\ntemplate:\n  name: ${TEMPLATE.name}\n  version: ${TEMPLATE.version}\n  source: builtin\nfiles:\n${entries}\n`;
+}
+function writeAtomically(destination, content) {
+    const temporary = `${destination}.peos-tmp-${process.pid}`;
+    fs.writeFileSync(temporary, content, "utf8");
+    fs.renameSync(temporary, destination);
+}
+export function init(target, dryRun = false, template = "node-service") {
+    if (template !== "node-service")
+        throw new Error(`PEOS_TEMPLATE_NOT_FOUND: ${template}`);
+    const root = path.resolve(target);
+    const name = projectName(root);
+    const files = filesFor(name);
+    if (fs.existsSync(path.join(root, ".peos", "project.yaml")))
+        throw new Error("PEOS_INIT_ALREADY_INITIALIZED");
+    const conflicts = files.map(([file]) => file).filter(file => fs.existsSync(path.join(root, file)));
+    if (conflicts.length)
+        throw new Error(`PEOS_INIT_CONFLICT: ${conflicts.join(", ")}`);
+    const allFiles = [...files, [".peos/manifest.yaml", manifest(name, files)]];
+    if (dryRun) {
+        console.log(`\n${color("1", "Preview initialization")} ${color("2", `· ${root}`)}`);
+        console.log(`\n  ${color("36", TEMPLATE.name)} ${color("2", `v${TEMPLATE.version}`)}`);
+        allFiles.forEach(([file]) => console.log(`  create ${file}`));
+        return;
+    }
+    allFiles.forEach(([file, content]) => {
+        const destination = path.join(root, file);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        writeAtomically(destination, content);
+    });
+    console.log(`\n${color("1", "Project ready")} ${color("2", `· ${root}`)}\n`);
+    step("Foundation created", `${allFiles.length} files`);
+    step("Template applied", `${TEMPLATE.name}@${TEMPLATE.version}`);
+    step("Context generated", ".peos/generated/engineering-environment.md");
+    console.log(`\n  Next: ${color("36", `cd ${root}`)} && ${color("36", "npm install")}`);
+}
+export function listTemplates() {
+    console.log(`${TEMPLATE.name}\t${TEMPLATE.version}\t${TEMPLATE.description}`);
+}
+export function showTemplate(name = TEMPLATE.name) {
+    if (name !== TEMPLATE.name)
+        throw new Error(`PEOS_TEMPLATE_NOT_FOUND: ${name}`);
+    console.log(`${TEMPLATE.name}@${TEMPLATE.version}\n\n${TEMPLATE.description}\n\nFiles:\n${templateFiles.map(file => `- ${file}`).join("\n")}`);
+}
+export function validateTemplate(name = TEMPLATE.name) {
+    if (name !== TEMPLATE.name)
+        throw new Error(`PEOS_TEMPLATE_NOT_FOUND: ${name}`);
+    console.log(`✓ ${TEMPLATE.name}@${TEMPLATE.version} is valid`);
+}
+export function inspectContext(target = ".") {
+    const context = path.join(path.resolve(target), ".peos", "generated", "engineering-environment.md");
+    if (!fs.existsSync(context))
+        throw new Error("PEOS_CONTEXT_NOT_FOUND");
+    const content = fs.readFileSync(context, "utf8");
+    const links = [...content.matchAll(/^- \[([^\]]+)\]\(([^)]+)\)$/gm)].map(match => `${match[1]} → ${match[2]}`);
+    console.log(`Context: ${context}\nBytes: ${Buffer.byteLength(content, "utf8")}\nIncluded documents:\n${links.length ? links.map(link => `- ${link}`).join("\n") : "- none"}`);
+}
+export function doctor(target = ".") {
+    const root = path.resolve(target);
+    const manifestPath = path.join(root, ".peos", "manifest.yaml");
+    if (!fs.existsSync(manifestPath))
+        throw new Error("PEOS_NOT_INITIALIZED");
+    const manifestText = fs.readFileSync(manifestPath, "utf8");
+    const entries = [...manifestText.matchAll(/^  - path: (.+)\n    sha256: ([a-f0-9]{64})$/gm)];
+    const problems = [];
+    if (!fs.existsSync(path.join(root, ".peos", "project.yaml")))
+        problems.push("missing .peos/project.yaml");
+    for (const [, file, expected] of entries) {
+        const destination = path.join(root, file);
+        if (!fs.existsSync(destination))
+            problems.push(`missing ${file}`);
+        else if (crypto.createHash("sha256").update(fs.readFileSync(destination)).digest("hex") !== expected)
+            problems.push(`modified ${file}`);
+    }
+    if (problems.length) {
+        console.log(`✗ PEOS health check failed\n${problems.map(problem => `- ${problem}`).join("\n")}`);
+        return false;
+    }
+    console.log(`✓ PEOS project is healthy (${entries.length} managed files)`);
+    return true;
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args[0] === "template") {
+        const action = args[1] ?? "list";
+        const name = args[2] ?? TEMPLATE.name;
+        if (action === "list")
+            return listTemplates();
+        if (action === "show")
+            return showTemplate(name);
+        if (action === "validate")
+            return validateTemplate(name);
+        throw new Error("Usage: peos template [list|show|validate] [name]");
+    }
+    if (args[0] === "context" && args[1] === "inspect")
+        return inspectContext(args[2] ?? ".");
+    if (args[0] === "doctor") {
+        if (!doctor(args[1] ?? "."))
+            process.exitCode = 1;
+        return;
+    }
+    if (args[0] !== "init")
+        throw new Error("Usage: peos init [target] [--template <name>] [--dry-run]");
+    let target = ".";
+    let template = "node-service";
+    for (let i = 1; i < args.length; i += 1) {
+        if (args[i] === "--dry-run")
+            continue;
+        if (args[i] === "--template") {
+            template = args[++i] ?? "";
+            continue;
+        }
+        if (args[i].startsWith("--template=")) {
+            template = args[i].slice("--template=".length);
+            continue;
+        }
+        if (args[i].startsWith("--"))
+            throw new Error(`Unknown option: ${args[i]}`);
+        if (target !== ".")
+            throw new Error("Usage: peos init [target] [--template <name>] [--dry-run]");
+        target = args[i];
+    }
+    init(target, args.includes("--dry-run"), template);
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
+    try {
+        console.log(`\n${logo()}\n`);
+        main();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\n${color("31", "✗")} ${message}`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@parthiv-joshi-29/peos",
+  "version": "0.1.0",
+  "description": "A small, local-first project foundation generator.",
+  "engines": { "node": ">=22" },
+  "type": "module",
+  "publishConfig": { "access": "public" },
+  "files": ["dist"],
+  "bin": { "peos": "dist/cli.js" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/init.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}