appsec 0.1.0__py3-none-any.whl

appsec/__init__.py

@@ -0,0 +1,11 @@
+"""appsec — an application-security agent (greenfield AgentCulture sibling)."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _v
+
+try:
+    __version__ = _v("appsec")
+except PackageNotFoundError:  # pragma: no cover  — editable install without metadata
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

appsec/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running appsec as ``python -m appsec``."""
+
+import sys
+
+from appsec.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

appsec/cli/__init__.py

@@ -0,0 +1,105 @@
+"""Unified CLI entry point for appsec.
+
+Error-propagation contract: every handler raises
+:class:`appsec.cli._errors.AppsecError` on failure; ``main()`` catches it via
+:func:`_dispatch` and routes through :mod:`appsec.cli._output`. Unknown
+exceptions are wrapped into an ``AppsecError`` so no Python traceback leaks.
+
+Argparse errors (unknown verb, missing required arg) also route through the
+structured format — :class:`_AppsecArgumentParser` overrides ``.error()``.
+Whether errors render as text or JSON depends on whether ``--json`` appears in
+the raw argv (:func:`main` sets ``_AppsecArgumentParser._json_hint`` before
+``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from appsec import __version__
+from appsec.cli._errors import EXIT_USER_ERROR, AppsecError
+from appsec.cli._output import emit_error
+
+
+class _AppsecArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`."""
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = AppsecError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=type(self)._json_hint)
+        raise SystemExit(err.code)
+
+
+def _argv_has_json(argv: list[str] | None) -> bool:
+    tokens = argv if argv is not None else sys.argv[1:]
+    return any(t == "--json" or t.startswith("--json=") for t in tokens)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _AppsecArgumentParser(
+        prog="appsec",
+        description="appsec — an application-security agent (greenfield).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", parser_class=_AppsecArgumentParser)
+
+    from appsec.cli._commands import explain as _explain_cmd
+    from appsec.cli._commands import learn as _learn_cmd
+    from appsec.cli._commands import whoami as _whoami_cmd
+
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _whoami_cmd.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    A handler may return ``None`` (treated as success, exit 0) or an ``int``
+    used directly as the exit code. Failures MUST raise :class:`AppsecError`;
+    any other exception is wrapped so no Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except AppsecError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort; wrap and route cleanly
+        wrapped = AppsecError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/appsec/issues",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    _AppsecArgumentParser._json_hint = _argv_has_json(argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

appsec/cli/_commands/explain.py

@@ -0,0 +1,40 @@
+"""``appsec explain`` — placeholder verb.
+
+See :mod:`appsec.cli._commands.learn` for why the verbs are stubs. ``explain``
+will eventually print docs for a given topic / command path; today it prints
+an honest "not yet implemented" line.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from appsec import __version__
+from appsec.cli._output import emit_result
+
+_TEXT = "appsec explain — not yet implemented; appsec is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "appsec",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "explain",
+        "message": _TEXT,
+    }
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("explain", help="Explain an appsec topic or command (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

appsec/cli/_commands/learn.py

@@ -0,0 +1,44 @@
+"""``appsec learn`` — placeholder verb.
+
+appsec is a greenfield AgentCulture sibling: the scaffold (package, CLI
+chassis, CI, vendored skills) is in place but the application-security agent
+itself is not implemented yet. This verb prints an honest status line so a
+probing agent or human gets a clear signal rather than a misleading response.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from appsec import __version__
+from appsec.cli._output import emit_result
+
+_TEXT = (
+    "appsec — application-security agent. Not yet implemented; appsec is a "
+    "greenfield AgentCulture sibling. See CLAUDE.md."
+)
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "appsec",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "learn",
+        "message": _TEXT,
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("learn", help="Print appsec's self-teaching status line.")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

appsec/cli/_commands/whoami.py

@@ -0,0 +1,40 @@
+"""``appsec whoami`` — placeholder verb.
+
+See :mod:`appsec.cli._commands.learn` for why the verbs are stubs. ``whoami``
+will eventually be the smallest identity / auth probe; today it prints an
+honest "not yet implemented" line.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from appsec import __version__
+from appsec.cli._output import emit_result
+
+_TEXT = "appsec — not yet implemented; appsec is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "appsec",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "whoami",
+        "message": _TEXT,
+    }
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("whoami", help="Print appsec's identity probe (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

appsec/cli/_errors.py

@@ -0,0 +1,39 @@
+"""AppsecError and exit-code policy.
+
+Every failure inside appsec raises :class:`AppsecError`. The top-level
+``main()`` catches it, formats via :mod:`appsec.cli._output`, and exits with
+:attr:`AppsecError.code`. This centralises the exit-code policy and guarantees
+no Python traceback leaks to stderr.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy:
+#   0  = success
+#   1  = user-input error (bad flag, missing required arg, unknown path)
+#   2  = environment / setup error (tool not installed, file unreadable)
+#   3+ = reserved for future categorisation
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class AppsecError(Exception):
+    """Structured error raised within appsec; carries a remediation hint."""
+
+    code: int
+    message: str
+    remediation: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "remediation": self.remediation,
+        }

appsec/cli/_output.py

@@ -0,0 +1,45 @@
+"""stdout / stderr helpers with a strict split.
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing appsec output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — it never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from appsec.cli._errors import AppsecError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (text or JSON), newline-terminated."""
+    s = stream if stream is not None else sys.stdout
+    if json_mode:
+        json.dump(data, s, ensure_ascii=False)
+        s.write("\n")
+        return
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: AppsecError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write an :class:`AppsecError` to stderr (text or JSON)."""
+    s = stream if stream is not None else sys.stderr
+    if json_mode:
+        json.dump(err.to_dict(), s, ensure_ascii=False)
+        s.write("\n")
+        return
+    s.write(f"error: {err.message}\n")
+    if err.remediation:
+        s.write(f"hint: {err.remediation}\n")
+
+
+def emit_diagnostic(message: str, *, stream: TextIO | None = None) -> None:
+    """Write a human diagnostic (progress, summary) to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")

appsec-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: appsec
+Version: 0.1.0
+Summary: appsec — an application-security agent (greenfield AgentCulture sibling).
+Project-URL: Homepage, https://github.com/agentculture/appsec
+Project-URL: Issues, https://github.com/agentculture/appsec/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# appsec
+
+An appsec agent

appsec-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+appsec/__init__.py,sha256=uHDR0tMi7OlgoyGHiKNhrXeg6Sk2ZYehs64wgr76wgY,364
+appsec/__main__.py,sha256=qjWptLDZzLmK3YjzbzhgdJKdaZxuj_y4rWR_HXotJ5k,142
+appsec/cli/__init__.py,sha256=bNp4BLlqyHu6-YzEOiDUHkHK-oqeoGJeVm_rj_y9x4g,3510
+appsec/cli/_errors.py,sha256=pXt9Kz7yIX2lrudbxt6doQcAjgGE5Kh4UhCexkP_7oE,1101
+appsec/cli/_output.py,sha256=H2dNXc1jsBvPId3SzeSQazEW5SFeu0YttZN4licSBGE,1543
+appsec/cli/_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+appsec/cli/_commands/explain.py,sha256=Avc91wx1rZU2HvkFQoEwQhDywXNPP1Cd3SnwJiGQ7AE,1165
+appsec/cli/_commands/learn.py,sha256=GkqWMqFsBNPVaMtgShY2vw0qSOEZycdjop4_gmzlLbs,1320
+appsec/cli/_commands/whoami.py,sha256=IIpcAJRvA28krghkBLbPQKMiXookUCTfeb1xvilPEaI,1140
+appsec-0.1.0.dist-info/METADATA,sha256=jku8VnReCOYwWrM5Kt9ZBfsunM1bG8IAaxFmCpT0_Ng,654
+appsec-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+appsec-0.1.0.dist-info/entry_points.txt,sha256=PvR0G1hKw0s9YAco6SB_pIuz4_gI6RouIatLASN-jcI,43
+appsec-0.1.0.dist-info/licenses/LICENSE,sha256=wCcdPywGtFXx1P8N0j0eEDINSWfSjrIsU7ds1YZl-MA,1069
+appsec-0.1.0.dist-info/RECORD,,

appsec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

appsec-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+appsec = appsec.cli:main

appsec-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentCulture
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.