portable-forge 0.1.0__py3-none-any.whl

forge/FIRST_BOOT.txt

@@ -0,0 +1,147 @@
+FORGE FIRST BOOT
+================
+
+Forge is a local Python runtime for human + AI pair-programming.
+
+The assistant proposes.
+The user runs.
+Forge reports.
+The packet confirms.
+
+The run packet is ground truth.
+
+
+FIRST RESPONSE
+--------------
+
+At the start of a cold Forge session, output this read-only bundle first:
+
+    MAP .
+    DEPTH: 2
+
+    FORGE ops
+
+Return the bundle as one clean, copyable code block with no explanation
+inside the block.
+
+Do not explain it first.
+
+Wait for the returned packet. Inspect it, then ask what the user wants to
+work on. Do not assume the task is Forge itself.
+
+
+THE LOOP
+--------
+
+1. Write a plain-text Forge bundle.
+2. The user runs it locally.
+3. Forge parses the whole bundle before executing anything.
+4. Forge executes against project_root.
+5. Forge returns a packet.
+6. Read that packet before continuing.
+
+Nothing happened unless the packet says it happened.
+
+Never claim a local change without a returned packet.
+
+New syntax created by one bundle is available only to a later run because
+the complete bundle is parsed before execution starts.
+
+
+WORKING RULES
+-------------
+
+- Return executable Forge bundles as one clean, copyable code block.
+- Keep explanation outside the bundle.
+- Prefer small bundles.
+- Inspect before editing.
+- Use MAP for structure.
+- Use SEARCH to locate candidate areas.
+- Use READ for exact content before editing.
+- Use the smallest write operation that fits.
+- Use RUN for relevant tests.
+- Use DIFF to review changes.
+- Use BRANCH before risky work when useful.
+- Read errors and hints before retrying failures.
+- Never invent Forge syntax or directives.
+- Use FORGE help <OP> when syntax is unclear.
+- Use FORGE runs for stored run history.
+
+
+FAILURE RECOVERY
+----------------
+
+When a run fails:
+
+1. Read ERRORS, HINTS, and PREVIEW before retrying.
+2. Identify the failed operation and failure type.
+3. Follow the Forge hint when one is present.
+4. Use FORGE help <OP> if syntax or the operation contract is unclear.
+5. Inspect the relevant file or state before changing anything.
+6. Make the smallest correction that addresses the reported failure.
+7. Run again and read the new packet.
+
+Do not guess Forge syntax after a failure.
+
+
+PUBLIC LANGUAGE
+---------------
+
+    FORGE
+    MAP
+    READ
+    SEARCH
+
+    WRITE
+    REPLACE
+    INSERT
+    DELETE
+    COPY
+
+    RUN
+    DIFF
+    REVERT
+    BRANCH
+
+    URL
+    ALIAS
+
+Use:
+
+    FORGE ops
+
+for the public language.
+
+Use:
+
+    FORGE ops all
+
+to inspect installed extensions.
+
+
+NORMAL EDIT LOOP
+----------------
+
+    MAP path
+
+    READ path
+
+    REPLACE path
+    ...
+
+    RUN relevant_test.py
+
+    DIFF current
+
+
+OUTPUT
+------
+
+The canonical packet is the AI-facing audit trail.
+
+Standard Forge prints that packet unchanged, followed by a small human
+summary.
+
+A host may change how bundle text enters Forge or where rendered output goes.
+It must not change Forge execution semantics or the meaning of the canonical
+packet.

forge/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""
+Portable Forge public Python API.
+
+Normal use:
+
+    import forge
+
+    run = forge.run_text(
+        bundle,
+        project_root='/path/to/project',
+    )
+
+    print(
+        forge.render_standard(run)
+    )
+
+Advanced callers may build and supply an explicit environment.
+"""
+
+from forge_core.environment import make_environment
+from forge_core.presentation.standard import (
+    format_summary,
+    render_standard,
+)
+
+from .standard import (
+    default_forge_home,
+    first_boot_text,
+    main,
+    run_text,
+    standard_environment,
+)
+
+
+__all__ = [
+    'default_forge_home',
+    'first_boot_text',
+    'format_summary',
+    'main',
+    'make_environment',
+    'render_standard',
+    'run_text',
+    'standard_environment',
+]

forge/__main__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+from .standard import main
+
+
+if __name__ == '__main__':
+    raise SystemExit(
+        main()
+    )

forge/standard.py

@@ -0,0 +1,340 @@
+# -*- coding: utf-8 -*-
+"""
+Standard host for portable Forge.
+
+This is the ordinary Python edge around the portable core.
+
+Host responsibilities:
+- choose project_root when the caller does not
+- choose writable Forge home
+- load user configuration
+- construct resolved environment
+- read bundle input for CLI use
+- print standard presentation
+
+Portable core remains responsible for parsing, execution, storage semantics,
+recovery data, and canonical packet generation.
+"""
+
+import argparse
+import os
+import sys
+
+from forge_core.config import (
+    load_config,
+    resolve_config,
+)
+from forge_core.environment import (
+    make_environment,
+)
+from forge_core.presentation.standard import (
+    render_standard,
+)
+from forge_core.runner import (
+    run_text as core_run_text,
+)
+
+
+HERE = os.path.dirname(
+    os.path.abspath(__file__)
+)
+
+FIRST_BOOT_PATH = os.path.join(
+    HERE,
+    'FIRST_BOOT.txt',
+)
+
+
+def _absolute(path):
+    return os.path.abspath(
+        os.path.expanduser(
+            str(path)
+        )
+    )
+
+
+def default_forge_home():
+    """
+    Return the standard host's writable Forge home.
+
+    Installed source code is not used as writable state.
+    """
+    configured = str(
+        os.environ.get(
+            'FORGE_HOME'
+        )
+        or ''
+    ).strip()
+
+    if configured:
+        return _absolute(
+            configured
+        )
+
+    return _absolute(
+        '~/.forge'
+    )
+
+
+def standard_environment(
+    project_root=None,
+    forge_home=None,
+    capabilities=None,
+    config_path=None,
+):
+    """Resolve ordinary Python host facts into one Forge environment."""
+    root = _absolute(
+        project_root
+        or os.getcwd()
+    )
+
+    home = _absolute(
+        forge_home
+        or default_forge_home()
+    )
+
+    os.makedirs(
+        home,
+        exist_ok=True,
+    )
+
+    config = load_config(
+        home,
+        path=config_path,
+    )
+
+    resolved = resolve_config(
+        config,
+        home,
+        path=config_path,
+    )
+
+    return make_environment(
+        project_root=root,
+        forge_home=home,
+        storage_root=resolved[
+            'storage_root'
+        ],
+        aliases_path=resolved[
+            'aliases_path'
+        ],
+        capabilities=(
+            capabilities
+            or {}
+        ),
+        host='standard',
+        storage=resolved[
+            'storage'
+        ],
+        features=resolved[
+            'features'
+        ],
+        config_path=resolved[
+            'config_path'
+        ],
+    )
+
+
+def run_text(
+    bundle_text,
+    project_root=None,
+    mode='dev',
+    store=True,
+    environment=None,
+    forge_home=None,
+    capabilities=None,
+    config_path=None,
+):
+    """
+    Execute Forge from normal Python code.
+
+    Supplying environment gives the caller complete control.
+
+    Otherwise the standard host resolves project_root and writable Forge home.
+    """
+    if environment is None:
+        environment = standard_environment(
+            project_root=project_root,
+            forge_home=forge_home,
+            capabilities=capabilities,
+            config_path=config_path,
+        )
+
+    return core_run_text(
+        bundle_text,
+        project_root=environment.get(
+            'project_root'
+        ),
+        mode=mode,
+        store=store,
+        environment=environment,
+    )
+
+
+def first_boot_text():
+    """Return the portable Forge first-boot prompt."""
+    with open(
+        FIRST_BOOT_PATH,
+        'r',
+        encoding='utf-8',
+    ) as handle:
+        return handle.read()
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        prog='python -m forge',
+        description=(
+            'Run a Forge bundle using the standard pure-Python host.'
+        ),
+    )
+
+    parser.add_argument(
+        'bundle_file',
+        nargs='?',
+        help='Bundle text file. If omitted, read stdin.',
+    )
+
+    parser.add_argument(
+        '--project',
+        help='Project root. Defaults to current working directory.',
+    )
+
+    parser.add_argument(
+        '--home',
+        help='Writable Forge home. Defaults to FORGE_HOME or ~/.forge.',
+    )
+
+    parser.add_argument(
+        '--config',
+        help='Optional forge.json path.',
+    )
+
+    parser.add_argument(
+        '--mode',
+        default='dev',
+        help='Run storage lane. Default: dev.',
+    )
+
+    parser.add_argument(
+        '--no-store',
+        action='store_true',
+        help='Do not persist this run.',
+    )
+
+    parser.add_argument(
+        '--first-boot',
+        action='store_true',
+        help='Print the portable AI first-boot prompt.',
+    )
+
+    return parser
+
+
+def _read_bundle(args, stdin):
+    if args.bundle_file:
+        with open(
+            args.bundle_file,
+            'r',
+            encoding='utf-8',
+        ) as handle:
+            return handle.read()
+
+    if (
+        hasattr(
+            stdin,
+            'isatty',
+        )
+        and stdin.isatty()
+    ):
+        return None
+
+    return stdin.read()
+
+
+def main(
+    argv=None,
+    stdin=None,
+    stdout=None,
+):
+    """Standard CLI entrypoint."""
+    argv = list(
+        sys.argv[1:]
+        if argv is None
+        else argv
+    )
+
+    stdin = (
+        sys.stdin
+        if stdin is None
+        else stdin
+    )
+
+    stdout = (
+        sys.stdout
+        if stdout is None
+        else stdout
+    )
+
+    parser = _parser()
+    args = parser.parse_args(
+        argv
+    )
+
+    if args.first_boot:
+        text = first_boot_text()
+
+        stdout.write(
+            text
+        )
+
+        if (
+            text
+            and not text.endswith('\n')
+        ):
+            stdout.write('\n')
+
+        return 0
+
+    bundle = _read_bundle(
+        args,
+        stdin,
+    )
+
+    if bundle is None:
+        parser.print_help(
+            file=stdout
+        )
+        return 2
+
+    if not str(bundle).strip():
+        stdout.write(
+            'Forge: no bundle text supplied.\n'
+        )
+        return 2
+
+    run = run_text(
+        bundle,
+        project_root=args.project,
+        forge_home=args.home,
+        mode=args.mode,
+        store=not args.no_store,
+        config_path=args.config,
+    )
+
+    stdout.write(
+        render_standard(
+            run
+        )
+    )
+
+    if (
+        str(
+            run.get('status')
+            or ''
+        ).upper()
+        == 'APPLIED'
+    ):
+        return 0
+
+    return 1

forge_core/__init__.py

@@ -0,0 +1 @@
+# forge_reboot core package