@buba_71/levit 0.3.0

package/README.md

@@ -0,0 +1,136 @@
+# levit-kit
+
+Hybrid starter kit for **Antigravity** projects  
+(template + CLI + agentic conventions)
+
+---
+
+## Table of contents
+
+- [Why levit-kit exists](#why-levit-kit-exists)
+- [What levit-kit does](#what-levit-kit-does)
+- [What levit-kit does not do](#what-levit-kit-does-not-do)
+- [How levit-kit is used](#how-levit-kit-is-used)
+- [Where does the levit command come from](#where-does-the-levit-command-come-from)
+- [Social Contract](#social-contract)
+- [Nature of the project](#nature-of-the-project)
+- [Status](#status)
+- [Contributing](#contributing)
+- [Guiding principle](#guiding-principle)
+
+---
+
+## Why levit-kit exists
+
+Levit-kit provides a **clean, readable, and predictable starting point** for initiating projects with Google Antigravity.
+
+It does not attempt to automate development, orchestrate agents, or generate business logic.
+
+Its role is simple:  
+👉 **install a clear framework in which humans and agents can work properly.**
+
+---
+
+## What levit-kit does
+
+- Initializes a standardized project structure
+- Installs explicit conventions
+- Facilitates human and agent onboarding
+- Reduces unnecessary variability between projects
+
+---
+
+## What levit-kit does not do
+
+- It does not generate business logic
+- It makes no functional decisions
+- It does not execute or orchestrate agents
+- It imposes no workflow
+- It introduces no magic
+
+These limits are intentional.
+
+---
+
+## How levit-kit is used
+
+Levit-kit is used **once**, at the very beginning of a project.
+
+```bash
+npx levit init my-project
+```
+
+This command:
+- creates a new project directory
+- copies the default levit-kit template
+- installs no dependency
+- exits immediately
+
+Levit-kit does not remain in the project after initialization.
+
+---
+
+## Where does the levit command come from?
+
+The `levit` command is provided through the npm ecosystem.
+
+Levit-kit is published as an npm package exposing a CLI binary named `levit`.
+When running the command above, `npx`:
+
+- downloads the package temporarily
+- executes the `levit` CLI
+- removes it after execution
+
+Nothing is installed in the generated project.
+
+---
+
+## Social Contract
+
+The behavior, boundaries, and evolution of levit-kit are defined in a foundational document:
+
+📄 **[SOCIAL_CONTRACT.md](./SOCIAL_CONTRACT.md)**
+
+👉 All technical decisions, issues, and contributions are evaluated against this contract.
+
+---
+
+## Nature of the project
+
+Levit-kit is a **hybrid tool**:
+
+- a project **template**
+- an initialization **CLI**
+- a set of **agentic conventions**
+
+Each component remains deliberately simple and decoupled.
+
+---
+
+## Status
+
+- Phase: foundation
+- Stability: being defined
+- Target audience: developers working with Antigravity
+
+---
+
+## Contributing
+
+Before contributing, please read the social contract.
+
+Contributions aiming to:
+- simplify,
+- clarify,
+- stabilize
+
+are welcome.
+
+Contributions adding complexity, implicit automation, or decision-making logic will be rejected.
+
+---
+
+## Guiding principle
+
+> Levit-kit does not make agents smarter.  
+> It makes projects more intelligible.

package/SOCIAL_CONTRACT.md

@@ -0,0 +1,123 @@
+# levit-kit Social Contract
+
+Version: 0.1  
+Status: Foundational  
+Scope: Non-negotiable
+
+---
+
+## 1. Purpose
+
+Levit-kit exists to provide a **clean, readable, and predictable starting point** for Antigravity projects.
+
+It does not aim to:
+- artificially speed up development,
+- replace human judgment,
+- or hide the inherent complexity of agentic systems.
+
+Its role is **structural**, not decision-making.
+
+---
+
+## 2. What levit-kit does
+
+Levit-kit:
+
+1. Initializes a clear and stable project structure
+2. Provides explicit conventions
+3. Creates a framework understandable by both humans and agents
+4. Reduces unnecessary variability between projects
+5. Facilitates human and agent onboarding
+
+Nothing more.
+
+---
+
+## 3. What levit-kit will never do
+
+Levit-kit will never:
+
+- generate business logic
+- make functional decisions
+- orchestrate agents
+- execute workflows
+- infer user intent
+- perform automatic optimizations
+
+These refusals are final.
+
+---
+
+## 4. Relationship with AI agents
+
+Agents:
+
+- are guests, never sovereign
+- operate under explicit instructions
+- work within clearly defined boundaries
+- never modify foundations without human validation
+
+Levit-kit is **agent-aware**, not agent-driven.
+
+---
+
+## 5. Relationship with the human user
+
+The user:
+
+- remains responsible for decisions
+- understands what is installed
+- can modify the project without breaking levit-kit
+- is never locked into an imposed workflow
+
+Levit-kit introduces **no hidden dependencies**.
+
+---
+
+## 6. Conventions over configuration
+
+Levit-kit favors:
+
+- a single structure
+- few or no options
+- explicit, opinionated decisions
+
+Customization is possible **after initialization**, never during.
+
+---
+
+## 7. Project evolution
+
+Levit-kit evolves according to these rules:
+
+- few releases
+- explicit changes
+- compatibility over novelty
+- no feature without structural justification
+
+Any evolution must improve the **readability or stability** of generated projects.
+
+---
+
+## 8. Contributions
+
+Contributions are welcome if they:
+
+- simplify
+- clarify
+- reduce surface area
+- reinforce coherence
+
+Contributions introducing:
+- magic
+- opaque abstractions
+- implicit behaviors
+
+will be rejected, even if they appear useful.
+
+---
+
+## 9. Core principle
+
+> Levit-kit does not aim to save time.  
+> It aims to prevent losing time later.

package/dist/bin/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const init_1 = require("../src/init");
+const node_path_1 = __importDefault(require("node:path"));
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length !== 2 || args[0] !== "init") {
+        console.error("Usage: levit init <project-name>");
+        process.exit(1);
+    }
+    const projectName = args[1];
+    const targetPath = node_path_1.default.resolve(process.cwd(), projectName);
+    try {
+        (0, init_1.initProject)(projectName, targetPath);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : "Unexpected error");
+        process.exit(1);
+    }
+}
+main();

package/dist/src/init.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initProject = initProject;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function getPackageRoot() {
+    // process.argv[1] points to the executed CLI file
+    // e.g. /path/to/levit-kit/dist/bin/cli.js
+    return node_path_1.default.resolve(node_path_1.default.dirname(process.argv[1]), "..", "..");
+}
+function initProject(projectName, targetPath) {
+    const packageRoot = getPackageRoot();
+    const templatePath = node_path_1.default.join(packageRoot, "templates", "default");
+    if (!projectName) {
+        throw new Error("Project name is required.");
+    }
+    if (node_fs_1.default.existsSync(targetPath)) {
+        throw new Error(`Directory "${projectName}" already exists.`);
+    }
+    if (!node_fs_1.default.existsSync(templatePath)) {
+        throw new Error(`Default template not found at ${templatePath}`);
+    }
+    node_fs_1.default.mkdirSync(targetPath, { recursive: true });
+    copyDirectory(templatePath, targetPath);
+    console.log("");
+    console.log("levit-kit v1.0");
+    console.log("");
+    console.log("✔ Project directory created");
+    console.log("✔ Template copied");
+    console.log("");
+    console.log(`Project "${projectName}" initialized successfully.`);
+    console.log("");
+    console.log("Next steps:");
+    console.log("  - Open the project");
+    console.log("  - Read SOCIAL_CONTRACT.md");
+    console.log("  - Start defining features");
+}
+function copyDirectory(source, target) {
+    const entries = node_fs_1.default.readdirSync(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = node_path_1.default.join(source, entry.name);
+        const targetPath = node_path_1.default.join(target, entry.name);
+        if (entry.isDirectory()) {
+            node_fs_1.default.mkdirSync(targetPath, { recursive: true });
+            copyDirectory(sourcePath, targetPath);
+        }
+        else {
+            node_fs_1.default.copyFileSync(sourcePath, targetPath);
+        }
+    }
+}

package/dist/tests/init.test.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const init_1 = require("../src/init");
+function exists(p) {
+    return node_fs_1.default.existsSync(p);
+}
+(0, node_test_1.default)("levit init copies default template exactly", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "levit-kit-test-"));
+    const projectName = "test-project";
+    const projectPath = node_path_1.default.join(tempDir, projectName);
+    (0, init_1.initProject)(projectName, projectPath);
+    // Core structure assertions
+    node_assert_1.default.ok(exists(projectPath), "Project directory should exist");
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "README.md")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "SOCIAL_CONTRACT.md")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "agents")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "roles")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "pipelines")));
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "docs")));
+    // Agent boundaries
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "agents", "AGENTS.md")), "Agent guidelines should exist");
+    // Feature contract
+    node_assert_1.default.ok(exists(node_path_1.default.join(projectPath, "features", "README.md")), "Feature README should exist");
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@buba_71/levit",
+  "version": "0.3.0",
+  "description": "Hybrid starter kit for Antigravity projects",
+  "author": "David BUBA",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "levit": "dist/bin/cli.js"
+  },
+
+  "files": [
+    "dist",
+    "templates",
+    "SOCIAL_CONTRACT.md",
+    "README.md"
+  ],
+
+  "main": "dist/src/init.js",
+
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/bin/cli.js",
+    "test": "npm run build && node --test dist/tests"
+  },
+
+  "dependencies": {
+    "fs-extra": "^11.2.0"
+  },
+
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}

package/templates/default/README.md

@@ -0,0 +1,16 @@
+# Project Overview
+
+This project was initialized with **levit-kit**.
+
+Its purpose is to provide a **clear, predictable structure**
+for working with humans and AI agents.
+
+This repository:
+- contains no business logic
+- imposes no workflow
+- makes no automated decisions
+
+Start by reading:
+- SOCIAL_CONTRACT.md
+- agents/AGENTS.md
+- features/README.md

package/templates/default/SOCIAL_CONTRACT.md

@@ -0,0 +1,18 @@
+# Project Social Contract
+
+This project follows the levit-kit social contract.
+
+## Principles
+
+- Humans remain responsible for decisions
+- Agents are assistants, not decision-makers
+- Structure is explicit
+- Conventions are preferred over configuration
+
+## What this project does not do
+
+- No hidden automation
+- No implicit decisions
+- No enforced workflow
+
+This contract exists to preserve clarity over time.

package/templates/default/agents/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Guidelines
+
+Agents are allowed to:
+- propose changes
+- generate drafts
+- refactor existing code with approval
+
+Agents are not allowed to:
+- modify foundational documents
+- restructure the repository
+- introduce implicit behavior
+
+When unsure, agents must ask for human validation.

package/templates/default/agents/boundaries.md

@@ -0,0 +1,9 @@
+# Agent Boundaries
+
+Agents must respect the following boundaries:
+
+- Project structure is fixed
+- Contracts must not be altered implicitly
+- New conventions require human approval
+
+Boundaries are explicit and enforced by humans.

package/templates/default/docs/architecture.md

@@ -0,0 +1,11 @@
+# Architecture Notes
+
+This document records architectural decisions.
+
+Use it to:
+- explain structural choices
+- document trade-offs
+- preserve context over time
+
+Architecture evolves.
+Documentation preserves intent.

package/templates/default/features/README.md

@@ -0,0 +1,12 @@
+# Features
+
+A feature is a **contract**, not an implementation.
+
+Each feature document should define:
+- intent
+- inputs
+- outputs
+- constraints
+
+Features are discussed and validated here.
+Implementation happens elsewhere.

package/templates/default/pipelines/README.md

@@ -0,0 +1,8 @@
+# Pipelines
+
+This directory is reserved for automation.
+
+Add pipelines only when:
+- the need is explicit
+- the impact is understood
+- the behavior is documented

package/templates/default/roles/devops.md

@@ -0,0 +1,10 @@
+# DevOps Role
+
+This document defines DevOps responsibilities.
+
+Use it to document:
+- infrastructure assumptions
+- deployment constraints
+- operational requirements
+
+Avoid premature tooling decisions.

package/templates/default/roles/qa.md

@@ -0,0 +1,8 @@
+# QA Role
+
+This document defines quality responsibilities.
+
+Use it to describe:
+- quality standards
+- testing expectations
+- validation criteria

package/templates/default/roles/security.md

@@ -0,0 +1,8 @@
+# Security Role
+
+This document defines security expectations.
+
+Use it to record:
+- threat assumptions
+- security constraints
+- explicit security decisions