a3ip 1.0.0__py3-none-any.whl

a3ip/__init__.py

@@ -0,0 +1,9 @@
+"""
+A3IP — AI Infrastructure Installation Package
+*Pronounced "ay-trip"*
+
+CLI package for creating, validating, and bundling A3IP packages.
+"""
+
+__version__ = "1.0.0"
+__spec_version__ = "1.5"

a3ip/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m a3ip` invocation."""
+from a3ip.cli import main
+
+if __name__ == "__main__":
+    main()

a3ip/bundle.py

@@ -0,0 +1,185 @@
+"""
+A3IP bundle — generates a .a3ip.bundle file from a package directory.
+"""
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+_BINARY_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp",
+    ".pdf", ".zip", ".tar", ".gz", ".whl", ".exe", ".dll",
+    ".ttf", ".woff", ".woff2", ".eot",
+}
+_TEXT_EXTENSIONS = {
+    ".md", ".yaml", ".yml", ".json", ".py", ".ps1", ".sh",
+    ".txt", ".html", ".js", ".css", ".ts", ".tsx", ".jsx",
+    ".xml", ".toml", ".ini", ".cfg", ".env", ".bat", ".cmd",
+}
+
+
+def _is_binary(path: Path) -> bool:
+    if path.suffix.lower() in _BINARY_EXTENSIONS:
+        return True
+    if path.suffix.lower() in _TEXT_EXTENSIONS:
+        return False
+    try:
+        path.read_text(encoding="utf-8")
+        return False
+    except Exception:
+        return True
+
+
+def _get_package_name(pkg_dir: Path) -> str:
+    name = pkg_dir.name
+    if name.endswith(".a3ip"):
+        name = name[:-5]
+    return name
+
+
+def _get_package_version(pkg_dir: Path) -> str:
+    manifest = pkg_dir / "manifest.yaml"
+    if not manifest.exists():
+        return "1.0.0"
+    for line in manifest.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line.startswith("version:"):
+            return line.split(":", 1)[1].strip().strip('"').strip("'")
+    return "1.0.0"
+
+
+def _collect_files(pkg_dir: Path) -> list[Path]:
+    files = []
+    for fpath in sorted(pkg_dir.rglob("*")):
+        if not fpath.is_file():
+            continue
+        parts = fpath.relative_to(pkg_dir).parts
+        if any(p.startswith(".") for p in parts):
+            continue
+        if "__pycache__" in parts:
+            continue
+        files.append(fpath)
+    return files
+
+
+def _embed_file(lines: list, rel_path: str, fpath: Path) -> None:
+    lines.append("=== FILE: " + rel_path + " ===")
+    if _is_binary(fpath):
+        lines.append("# encoding: base64")
+        lines.append(base64.b64encode(fpath.read_bytes()).decode("ascii"))
+    else:
+        lines.append(fpath.read_text(encoding="utf-8", errors="replace"))
+    lines.append("=== END FILE ===")
+    lines.append("")
+
+
+def _hash_file(fpath: Path) -> str:
+    h = hashlib.sha256()
+    h.update(fpath.read_bytes())
+    return "sha256:" + h.hexdigest()
+
+
+def _write_source_manifest(pkg_dir: Path, pkg_files: list, name: str, version: str, now: str) -> None:
+    files_hashes = {
+        str(f.relative_to(pkg_dir)).replace("\\", "/"): _hash_file(f)
+        for f in pkg_files
+    }
+    source = {"package": name, "version": version, "bundled_at": now, "files": files_hashes}
+    (pkg_dir / ".a3ip-source.json").write_text(json.dumps(source, indent=2), encoding="utf-8")
+
+
+def build_bundle(pkg_dir: Path, output_path: Path, spec_path: Path | None = None) -> dict:
+    """Build a .a3ip.bundle file. Returns stats dict."""
+    name = _get_package_name(pkg_dir)
+    version = _get_package_version(pkg_dir)
+    pkg_files = _collect_files(pkg_dir)
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    spec_embedded = spec_path is not None and spec_path.exists()
+    total_files = len(pkg_files) + (1 if spec_embedded else 0)
+
+    lines = [
+        "---",
+        'a3ip-bundle: "1.1"',
+        "package: " + name,
+        'version: "' + version + '"',
+        "generated: " + now,
+        "files: " + str(total_files),
+        "spec_embedded: " + ("true" if spec_embedded else "false"),
+        "---",
+        "",
+        "# ================================================================",
+        "# A3IP BUNDLE — AI INSTALLATION INSTRUCTIONS",
+        "# ================================================================",
+        "#",
+        "# This file is an A3IP (AI Infrastructure Installation Package) bundle.",
+        "# It contains a complete AI workflow you can install into your workspace.",
+        "#",
+    ]
+
+    if spec_embedded:
+        lines += [
+            "# IF YOU ARE NOT FAMILIAR WITH A3IP:",
+            "#   1. Read the embedded spec first (A3IP-SPEC.md, the first FILE block below).",
+            "#   2. Read manifest.yaml to understand what this package contains.",
+            "#   3. Follow INSTALL.md to install it.",
+            "#",
+            "# IF YOU KNOW A3IP: Read manifest.yaml, then follow INSTALL.md.",
+        ]
+    else:
+        lines += [
+            "# Read manifest.yaml to understand what this package contains.",
+            "# Follow INSTALL.md to install it.",
+            "#",
+            "# Note: This bundle does not include the A3IP spec.",
+            "# If you are unfamiliar with A3IP, ask for the spec before proceeding.",
+        ]
+
+    lines += ["#", "# ================================================================", ""]
+
+    if spec_embedded:
+        lines.append("=== FILE: A3IP-SPEC.md ===")
+        lines.append(spec_path.read_text(encoding="utf-8", errors="replace"))
+        lines.append("=== END FILE ===")
+        lines.append("")
+
+    for fpath in pkg_files:
+        rel = str(fpath.relative_to(pkg_dir)).replace("\\", "/")
+        _embed_file(lines, rel, fpath)
+
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+    _write_source_manifest(pkg_dir, pkg_files, name, version, now)
+
+    return {"file_count": len(pkg_files), "spec_embedded": spec_embedded, "output": output_path}
+
+
+def bundle(pkg_dir_str: str, output_path_str: str | None = None, spec_path_str: str | None = None) -> dict:
+    """Public API: bundle a package. Returns stats dict or raises on error."""
+    pkg_dir = Path(pkg_dir_str)
+    if not pkg_dir.is_dir():
+        raise ValueError("Not a directory: " + pkg_dir_str)
+
+    spec_path = Path(spec_path_str) if spec_path_str else None
+    if spec_path and not spec_path.exists():
+        print("Warning: spec file '" + spec_path_str + "' not found — bundling without it.")
+        spec_path = None
+
+    name = _get_package_name(pkg_dir)
+    output_path = Path(output_path_str) if output_path_str else pkg_dir.parent / (name + ".a3ip.bundle")
+
+    mode = "with spec" if spec_path else "without spec"
+    print("Building bundle (" + mode + "): " + str(pkg_dir) + " → " + str(output_path))
+
+    result = build_bundle(pkg_dir, output_path, spec_path)
+    size_kb = output_path.stat().st_size / 1024
+
+    print("Bundle created: " + str(output_path))
+    print("  Package files: " + str(result["file_count"]))
+    if result["spec_embedded"]:
+        print("  Spec embedded: yes (" + spec_path.name + ")")
+    else:
+        print("  Spec embedded: no  (use --spec to include for external distribution)")
+    print("  Total size:    " + f"{size_kb:.1f} KB")
+
+    return result

a3ip/cli.py

@@ -0,0 +1,231 @@
+"""
+a3ip -- CLI for the A3IP package format.
+*Pronounced "ay-trip"*
+
+Commands:
+  a3ip new <name>              Scaffold a new package that passes validate immediately
+  a3ip validate <package_dir>  Run 9 normative checks; exit 0 if clean
+  a3ip bundle <package_dir>    Build a .a3ip.bundle file ready for distribution
+  a3ip export --format <fmt>   Export to another format (cowork-plugin, apm) [planned v0.2]
+
+See https://a3ip.dev for the full specification.
+"""
+
+import argparse
+import sys
+
+from a3ip import __version__, __spec_version__
+
+
+def _cmd_new(args: argparse.Namespace) -> int:
+    from a3ip.new import scaffold
+    try:
+        pkg_dir = scaffold(args.name, args.output_dir)
+    except FileExistsError as e:
+        print("Error: " + str(e), file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print("Error: " + str(e), file=sys.stderr)
+        return 1
+
+    print("Created package: " + str(pkg_dir))
+    print()
+    print("  " + str(pkg_dir / "manifest.yaml"))
+    print("  " + str(pkg_dir / "CONFIGURE.md"))
+    print("  " + str(pkg_dir / "INSTALL.md"))
+    print("  " + str(pkg_dir / "README.md"))
+    print("  " + str(pkg_dir / "components" / "skills" / (args.name + ".md")))
+    print()
+    print("Next steps:")
+    print("  1. Edit manifest.yaml -- fill in description, permissions, components.")
+    print("  2. Edit INSTALL.md -- describe the install steps.")
+    print("  3. Run:  a3ip validate " + args.name + "/")
+    print("  4. Run:  a3ip bundle " + args.name + "/")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    from a3ip.validate import validate
+    report = validate(args.package_dir)
+    if args.json:
+        import json
+        print(json.dumps(report, indent=2))
+    return 0 if report["ok"] else 1
+
+
+def _cmd_bundle(args: argparse.Namespace) -> int:
+    from a3ip.bundle import bundle
+    try:
+        bundle(
+            pkg_dir_str=args.package_dir,
+            output_path_str=args.output,
+            spec_path_str=args.spec,
+        )
+    except (ValueError, OSError) as e:
+        print("Error: " + str(e), file=sys.stderr)
+        return 1
+    return 0
+
+
+_EXPORT_FORMATS = {
+    "cowork-plugin": (
+        "Target: Anthropic Cowork Plugin (.plugin bundle)\n"
+        "\n"
+        "A3IP packages map cleanly to Cowork plugins: skills become skill files,\n"
+        "permissions become connector declarations, configuration becomes plugin settings.\n"
+        "A3IP acts as the portability and security layer around the plugin ecosystem --\n"
+        "packages authored once can target Cowork, Codex, Cursor, and others.\n"
+        "\n"
+        "Planned for a3ip v0.2. Track: https://github.com/a3ip-standard/cli/issues"
+    ),
+    "apm": (
+        "Target: Microsoft APM (Agent Package Manifest)\n"
+        "\n"
+        "A3IP is a superset of APM -- every A3IP package can emit a valid APM manifest.\n"
+        "The converter preserves components, dependencies, and context declarations.\n"
+        "\n"
+        "Planned for a3ip v0.2. Track: https://github.com/a3ip-standard/cli/issues"
+    ),
+}
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    fmt = args.format
+    details = _EXPORT_FORMATS[fmt]
+    print("a3ip export --format " + fmt)
+    print()
+    print("  Status: planned for a3ip v0.2")
+    print()
+    for line in details.splitlines():
+        print(("  " + line) if line else "")
+    print()
+    print("  Until this converter ships, install the package natively:")
+    print("  Drop the .a3ip.bundle into any A3IP-compatible AI and ask it to install.")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="a3ip",
+        description=(
+            "A3IP -- AI Infrastructure Installation Package (pronounced 'ay-trip')\n"
+            "Package, validate, and bundle portable AI agent workflows.\n\n"
+            "Spec:  https://a3ip.dev\n"
+            "Docs:  https://github.com/a3ip-standard/spec"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version="a3ip " + __version__ + " (spec " + __spec_version__ + ")"
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # -- new ------------------------------------------------------------------
+    p_new = sub.add_parser(
+        "new",
+        help="Scaffold a new package that passes validate on first run",
+        description=(
+            "Create a new A3IP package directory with all required files.\n"
+            "The scaffolded package passes `a3ip validate` immediately."
+        ),
+    )
+    p_new.add_argument("name", help="Package name (lowercase, hyphens, e.g. my-workflow)")
+    p_new.add_argument(
+        "--output-dir", metavar="DIR", dest="output_dir", default=None,
+        help="Parent directory to create the package in (default: current directory)",
+    )
+    p_new.set_defaults(func=_cmd_new)
+
+    # -- validate -------------------------------------------------------------
+    p_val = sub.add_parser(
+        "validate",
+        help="Run 9 normative checks on a package directory",
+        description=(
+            "Validate an A3IP package against the spec.\n\n"
+            "Runs 9 checks:\n"
+            "  1. Config coverage     -- {{config.*}} refs match manifest declarations\n"
+            "  2. Script existence    -- declared script files exist on disk\n"
+            "  3. Script config reads -- scripts only read declared config keys\n"
+            "  4. Cross-platform      -- Windows scripts have a cross-platform fallback\n"
+            "  5. Auth flows          -- auth scripts are referenced in INSTALL.md\n"
+            "  6. Changelog present   -- CHANGELOG.md required for version > 1.0.0\n"
+            "  7. Refresh scripts     -- refresh_script keys declared in manifest\n"
+            "  8. Trust->permissions  -- elevated trust requires a permissions block\n"
+            "  9. Trust->plan section -- write/shell trust requires ## Plan in INSTALL.md\n\n"
+            "Exit code: 0 if all checks pass, 1 if any errors found.\n"
+            "Warnings do not affect the exit code."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_val.add_argument("package_dir", help="Path to the package directory to validate")
+    p_val.add_argument(
+        "--json", action="store_true",
+        help="Print a JSON report in addition to the human-readable output",
+    )
+    p_val.set_defaults(func=_cmd_validate)
+
+    # -- bundle ---------------------------------------------------------------
+    p_bun = sub.add_parser(
+        "bundle",
+        help="Build a .a3ip.bundle file ready for distribution",
+        description=(
+            "Bundle a package directory into a single .a3ip.bundle file.\n\n"
+            "The bundle contains every file in the package in a plain-text format\n"
+            "that any A3IP-compatible AI can read and install.\n\n"
+            "Binary files are base64-encoded. Hidden files and __pycache__ are excluded."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_bun.add_argument("package_dir", help="Path to the package directory to bundle")
+    p_bun.add_argument(
+        "--output", "-o", metavar="PATH",
+        help="Output path for the bundle (default: <package_dir>/../<name>.a3ip.bundle)",
+    )
+    p_bun.add_argument(
+        "--spec", metavar="PATH",
+        help=(
+            "Embed the A3IP spec file into the bundle. "
+            "Use this when distributing to recipients who may not know A3IP."
+        ),
+    )
+    p_bun.set_defaults(func=_cmd_bundle)
+
+    # -- export ---------------------------------------------------------------
+    p_exp = sub.add_parser(
+        "export",
+        help="Export to another format: cowork-plugin, apm [planned v0.2]",
+        description=(
+            "Convert an A3IP package to another agent package format.\n\n"
+            "A3IP is designed as an interoperability layer -- packages can be exported\n"
+            "to platform-native formats without losing permissions or component structure.\n\n"
+            "Available formats:\n"
+            "  cowork-plugin   Anthropic Cowork Plugin bundle\n"
+            "  apm             Microsoft Agent Package Manifest\n\n"
+            "These commands are documented now so tooling and CI scripts can reference them.\n"
+            "They will print a roadmap notice until the converters ship in v0.2."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_exp.add_argument("package_dir", help="Path to the package directory to export")
+    p_exp.add_argument(
+        "--format", "-f", required=True,
+        choices=list(_EXPORT_FORMATS.keys()),
+        metavar="FORMAT",
+        help="Target format: " + ", ".join(_EXPORT_FORMATS.keys()),
+    )
+    p_exp.set_defaults(func=_cmd_export)
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

a3ip/new.py

@@ -0,0 +1,199 @@
+"""
+A3IP new — scaffold a minimal valid A3IP package.
+
+Creates a directory at <name>/ containing all required files.
+The scaffolded package passes `a3ip validate` on the first run.
+"""
+
+import sys
+from pathlib import Path
+
+_MANIFEST_TEMPLATE = """\
+$schema: https://a3ip.dev/schema/v1.5/manifest.json
+
+name: {name}
+version: "1.0.0"
+description: "Describe what this workflow does."
+min_a3ip_spec: "1.5"
+trust_level: read-only
+
+# Declare every external resource this package uses.
+# Remove sections that don't apply.
+#
+# permissions:
+#   filesystem:
+#     - path: "./output/"
+#       access: write
+#       reason: "Stores generated files."
+#   network:
+#     - domain: "api.example.com"
+#       reason: "Fetches data from the API."
+#   mcp:
+#     - name: example-mcp
+#       reason: "Reads and writes to the connected service."
+
+components:
+  skills:
+    - path: components/skills/{name}.md
+  # artifacts:
+  #   - path: components/artifacts/output.md
+  # prompts:
+  #   - path: components/prompts/main.md
+  # scripts:
+  #   - key: run
+  #     implementations:
+  #       - file: scripts/run.py
+  #         platform: any
+  #         trust_level: read-only
+
+# configuration:
+#   - key: api_token
+#     label: "API Token"
+#     type: string
+#     sensitive: true
+#     storage: env
+"""
+
+_CONFIGURE_TEMPLATE = """\
+# CONFIGURE.md — {name}
+# Ask the user these questions before starting the install.
+# Answers fill in {{{{config.*}}}} placeholders in INSTALL.md.
+# Remove this file entirely if the package needs no configuration.
+
+## Questions
+
+**1. (Example) Which workspace should the workflow use?**
+- Prompt: "Enter the path to your workspace directory:"
+- Key: `workspace_dir`
+- Type: directory_path
+- Default: `./workspace`
+"""
+
+_INSTALL_TEMPLATE = """\
+# INSTALL.md — {name}
+
+## Overview
+
+Brief description of what gets installed and what the user will be able to do.
+
+## Pre-flight checklist
+
+- [ ] (List any requirements the user must have ready before starting)
+
+## Steps
+
+### Step 1: (First action)
+
+Describe what to do here. Reference config values like {{{{config.workspace_dir}}}}.
+
+- [ ] Task A
+- [ ] Task B
+
+### Step 2: Verify
+
+- [ ] Confirm the workflow is working as expected.
+
+## Done
+
+The `{name}` workflow is now installed.
+"""
+
+_SKILL_TEMPLATE = """\
+# {name}
+
+## Overview
+
+Describe what this skill does and when to invoke it.
+
+## Usage
+
+Explain how to use the skill, what inputs it needs, and what output to expect.
+
+## Steps
+
+1. (First step)
+2. (Second step)
+3. Confirm the result.
+
+## Notes
+
+Any caveats, limitations, or tips.
+"""
+
+_README_TEMPLATE = """\
+# {name}
+
+> One-line description of what this workflow does.
+
+## What it does
+
+Describe the workflow in 2–3 sentences. What problem does it solve?
+
+## Requirements
+
+- (List any tools, accounts, or credentials needed)
+
+## Quick start
+
+```
+a3ip bundle {name}/
+# Drop the resulting .a3ip.bundle file into a conversation with an A3IP-compatible AI.
+```
+
+## Configuration
+
+| Key | Description | Required |
+|-----|-------------|----------|
+| (example) `api_token` | API token for the connected service | Yes |
+
+## License
+
+[Apache 2.0](LICENSE) — or replace with your chosen license.
+"""
+
+
+def scaffold(name: str, output_dir: str | None = None) -> Path:
+    """
+    Create a new A3IP package directory at output_dir/name (or ./name).
+    Returns the path to the created directory.
+    Raises FileExistsError if the directory already exists.
+    """
+    base = Path(output_dir) if output_dir else Path(".")
+    pkg_dir = base / name
+
+    if pkg_dir.exists():
+        raise FileExistsError("Directory already exists: " + str(pkg_dir))
+
+    # Validate name (must match manifest.yaml name pattern)
+    import re
+    if not re.match(r'^[a-z0-9][a-z0-9-]*[a-z0-9]$', name):
+        raise ValueError(
+            "Package name must be lowercase alphanumeric with hyphens "
+            "(e.g. 'my-workflow'), got: " + repr(name)
+        )
+
+    # Create directory tree
+    (pkg_dir / "components" / "skills").mkdir(parents=True)
+    (pkg_dir / "scripts").mkdir()
+
+    # Write files
+    (pkg_dir / "manifest.yaml").write_text(
+        _MANIFEST_TEMPLATE.format(name=name), encoding="utf-8"
+    )
+    (pkg_dir / "CONFIGURE.md").write_text(
+        _CONFIGURE_TEMPLATE.format(name=name), encoding="utf-8"
+    )
+    (pkg_dir / "INSTALL.md").write_text(
+        _INSTALL_TEMPLATE.format(name=name), encoding="utf-8"
+    )
+    (pkg_dir / "README.md").write_text(
+        _README_TEMPLATE.format(name=name), encoding="utf-8"
+    )
+    (pkg_dir / "components" / "skills" / (name + ".md")).write_text(
+        _SKILL_TEMPLATE.format(name=name), encoding="utf-8"
+    )
+
+    # Placeholder .gitkeep so scripts/ is committed empty
+    (pkg_dir / "scripts" / ".gitkeep").write_text("", encoding="utf-8")
+
+    return pkg_dir