# defapp Specification

## 1. Purpose

defapp is a modular CLI and standards engine for scaffolding new applications,
managing documentation templates, and auditing existing apps for compliance with
those standards.

## 2. Functional Requirements

### 2.1 Scaffolding CLI (newapp.sh)

- Provide a CLI entrypoint (newapp.sh) that supports subcommands:
  - init: scaffold a new application.
  - audit: check an existing app against standards.
  - help: show usage.

- init MUST:
  - Create a new app directory under a configured base (default: system value).
  - Use templates from templates/standards/newapp to generate:
    - Root files (README.md, .gitignore, scripts).
    - docs/ folder with standard Markdown documents.
  - Inject dynamic values: APP_NAME, APP_SLUG, APP_DATE, APP_DESCRIPTION.

- audit MUST:
  - Read a manifest file describing required files and sections.
  - Inspect a target app directory and report compliance/missing items.

### 2.2 Modularization

- Split functionality into logical modules:
  - folder: directory creation and path resolution.
  - customize: variable computation and configuration loading (.env files).
  - templates: reading manifest and rendering templates.
  - docs: documentation helpers.
  - audit: standards compliance checks.

- newapp.sh SHOULD act as a thin dispatcher calling module scripts/functions.

### 2.3 Configuration via .env

- System-wide configuration:
  - /home/intel145/websites/.env holds defaults (base path, org name, etc.).

- App-specific configuration:
  - /home/intel145/websites/apps/defapp.env holds defapp-specific overrides.

- defapp MUST:
  - Load system .env first, then app .env, with app values overriding system values.
  - Never commit actual .env files; instead, maintain an .env.example for documentation.

### 2.4 Standards and Manifest

- Standards templates are stored under templates/standards/newapp.
- Each standards version (newapp-v1, newapp-v2, etc.) MUST have a manifest.json
  describing package metadata, variables, templates, and required files/sections.

## 3. Non-Functional Requirements

- Bash-based, portable between Linux and macOS.
- Minimal external dependencies (envsubst, git, optional JSON tools).
- Clear logs and error messages for both init and audit commands.

## 4. Constraints

- Initial implementation targets single-user CLI under /home/intel145/websites.
- Later versions MAY support remote execution or integration with CI.