Productize Samsarix CLI and add its Samsarix roadmap - #1
Merged
Conversation
Summary by CodeRabbit
WalkthroughThis change replaces the legacy Helix CLI with Samsarix CLI, adds offline project templates and atomic scaffolding, introduces bounded project validation, updates packaging and licensing, and adds tests, CI, and product documentation. ChangesSamsarix CLI productization
Sequence Diagram(s)sequenceDiagram
participant User
participant SamsarixCLI
participant ScaffoldProject
participant TemplateRenderer
participant GeneratedProject
User->>SamsarixCLI: run init
SamsarixCLI->>ScaffoldProject: provide destination and template
ScaffoldProject->>TemplateRenderer: render selected template
TemplateRenderer-->>ScaffoldProject: return project files
ScaffoldProject->>GeneratedProject: stage and atomically install files
User->>SamsarixCLI: run check
SamsarixCLI->>GeneratedProject: read manifest and project metadata
GeneratedProject-->>SamsarixCLI: validation result
SamsarixCLI-->>User: human or JSON status
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Warning Tools execution failed with the following error: Failed to run tools: 14 UNAVAILABLE: read ECONNRESET Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@LICENSE`:
- Around line 1-201: Verify the Apache-2.0 title and provenance before
publication, and make the release gate require completion of that audit. In
LICENSE, confirm the license text and attribution requirements; update NOTICE at
lines 1-4 to accurately cover all included third-party work; and update
docs/PRODUCTIZATION.md at lines 211-212 and 229-234 so publication is
conditional on the completed provenance and attribution review.
In `@samsarix_cli/scaffold.py`:
- Around line 115-137: Adjust the staging-directory setup in the scaffold flow
around os.replace so the generated project root receives the process
umask-derived directory permissions instead of retaining mkdtemp’s 0700 mode.
Apply the umask to the staging root before replacing it with
resolved_destination, while leaving file generation and Git initialization
unchanged.
In `@samsarix_cli/templates.py`:
- Around line 52-54: Broaden the setuptools requirement in the build-system
template from the single-minor range to a supported floor with the existing
major-version cap, and update the matching hardcoded requirement in the README
so both remain synchronized.
- Around line 16-41: Update the run_command values in TEMPLATE_SPECS to use
clearly templated placeholder forms, including the project command and Streamlit
module path, so templates --json does not expose undocumented raw tokens. Keep
the existing command semantics and template names unchanged.
- Around line 108-180: Update the README template construction in the visible
template-rendering function so dedent is applied before interpolating the
multi-line configuration value, preserving normal Markdown indentation for
Discord-generated README files. Keep the existing README body and substitutions
unchanged, and strengthen the parametrized scaffold test to assert generated
README.md begins with “# ”.
In `@samsarix_cli/validation.py`:
- Around line 155-156: Update the requires-python validation in the
project-table check to parse the declared specifier and accept configurations
whose minimum supported Python version is 3.11 or newer, including values such
as >=3.12, rather than requiring exact equality with ">=3.11". Preserve
reporting an issue for missing, invalid, or lower minimum-version declarations.
- Around line 30-40: Update _read_bounded to enforce the byte cap during
reading: remove the preliminary path.stat size check and read at most limit + 1
bytes, then raise the existing safety-limit ValueError when more than limit
bytes are returned. Preserve the existing OSError-to-ValueError handling and
labels.
- Around line 94-95: Update the duplicate-path check in the manifest validation
logic to compare only string entries on both sides, so non-string values are
excluded from the duplicate count while still being handled by the existing
unsafe-path validation. Preserve duplicate detection for repeated string paths.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f90e1708-e086-4021-b566-36202da4987a
📒 Files selected for processing (35)
.github/workflows/ci.yml.gitignoreCHANGELOG.mdCONTRIBUTING.mdLICENSELICENSE.PROPRIETARYMANIFEST.inNOTICEREADME.mdROADMAP.mdSECURITY.mdTRADEMARKS.mddocs/PRODUCTIZATION.mdhelix_cli/__init__.pyhelix_cli/commands/__init__.pyhelix_cli/commands/config_cmd.pyhelix_cli/commands/deploy_cmd.pyhelix_cli/commands/init_cmd.pyhelix_cli/commands/monitor_cmd.pyhelix_cli/commands/project_cmd.pyhelix_cli/main.pypyproject.tomlsamsarix_cli/__init__.pysamsarix_cli/__main__.pysamsarix_cli/commands/__init__.pysamsarix_cli/commands/check_cmd.pysamsarix_cli/commands/init_cmd.pysamsarix_cli/commands/templates_cmd.pysamsarix_cli/main.pysamsarix_cli/scaffold.pysamsarix_cli/templates.pysamsarix_cli/validation.pytests/test_cli.pytests/test_scaffold.pytests/test_validation.py
💤 Files with no reviewable changes (9)
- LICENSE.PROPRIETARY
- helix_cli/commands/init_cmd.py
- helix_cli/commands/init.py
- helix_cli/commands/project_cmd.py
- helix_cli/commands/deploy_cmd.py
- helix_cli/commands/monitor_cmd.py
- helix_cli/commands/config_cmd.py
- helix_cli/main.py
- helix_cli/init.py
Comment on lines
+1
to
+201
| Apache License | ||
| Version 2.0, January 2004 | ||
| http://www.apache.org/licenses/ | ||
|
|
||
| TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION | ||
|
|
||
| 1. Definitions. | ||
|
|
||
| "License" shall mean the terms and conditions for use, reproduction, | ||
| and distribution as defined by Sections 1 through 9 of this document. | ||
|
|
||
| "Licensor" shall mean the copyright owner or entity authorized by | ||
| the copyright owner that is granting the License. | ||
|
|
||
| "Legal Entity" shall mean the union of the acting entity and all | ||
| other entities that control, are controlled by, or are under common | ||
| control with that entity. For the purposes of this definition, | ||
| "control" means (i) the power, direct or indirect, to cause the | ||
| direction or management of such entity, whether by contract or | ||
| otherwise, or (ii) ownership of fifty percent (50%) or more of the | ||
| outstanding shares, or (iii) beneficial ownership of such entity. | ||
|
|
||
| "You" (or "Your") shall mean an individual or Legal Entity | ||
| exercising permissions granted by this License. | ||
|
|
||
| "Source" form shall mean the preferred form for making modifications, | ||
| including but not limited to software source code, documentation | ||
| source, and configuration files. | ||
|
|
||
| "Object" form shall mean any form resulting from mechanical | ||
| transformation or translation of a Source form, including but | ||
| not limited to compiled object code, generated documentation, | ||
| and conversions to other media types. | ||
|
|
||
| "Work" shall mean the work of authorship, whether in Source or | ||
| Object form, made available under the License, as indicated by a | ||
| copyright notice that is included in or attached to the work | ||
| (an example is provided in the Appendix below). | ||
|
|
||
| "Derivative Works" shall mean any work, whether in Source or Object | ||
| form, that is based on (or derived from) the Work and for which the | ||
| editorial revisions, annotations, elaborations, or other modifications | ||
| represent, as a whole, an original work of authorship. For the purposes | ||
| of this License, Derivative Works shall not include works that remain | ||
| separable from, or merely link (or bind by name) to the interfaces of, | ||
| the Work and Derivative Works thereof. | ||
|
|
||
| "Contribution" shall mean any work of authorship, including | ||
| the original version of the Work and any modifications or additions | ||
| to that Work or Derivative Works thereof, that is intentionally | ||
| submitted to Licensor for inclusion in the Work by the copyright owner | ||
| or by an individual or Legal Entity authorized to submit on behalf of | ||
| the copyright owner. For the purposes of this definition, "submitted" | ||
| means any form of electronic, verbal, or written communication sent | ||
| to the Licensor or its representatives, including but not limited to | ||
| communication on electronic mailing lists, source code control systems, | ||
| and issue tracking systems that are managed by, or on behalf of, the | ||
| Licensor for the purpose of discussing and improving the Work, but | ||
| excluding communication that is conspicuously marked or otherwise | ||
| designated in writing by the copyright owner as "Not a Contribution." | ||
|
|
||
| "Contributor" shall mean Licensor and any individual or Legal Entity | ||
| on behalf of whom a Contribution has been received by Licensor and | ||
| subsequently incorporated within the Work. | ||
|
|
||
| 2. Grant of Copyright License. Subject to the terms and conditions of | ||
| this License, each Contributor hereby grants to You a perpetual, | ||
| worldwide, non-exclusive, no-charge, royalty-free, irrevocable | ||
| copyright license to reproduce, prepare Derivative Works of, | ||
| publicly display, publicly perform, sublicense, and distribute the | ||
| Work and such Derivative Works in Source or Object form. | ||
|
|
||
| 3. Grant of Patent License. Subject to the terms and conditions of | ||
| this License, each Contributor hereby grants to You a perpetual, | ||
| worldwide, non-exclusive, no-charge, royalty-free, irrevocable | ||
| (except as stated in this section) patent license to make, have made, | ||
| use, offer to sell, sell, import, and otherwise transfer the Work, | ||
| where such license applies only to those patent claims licensable | ||
| by such Contributor that are necessarily infringed by their | ||
| Contribution(s) alone or by combination of their Contribution(s) | ||
| with the Work to which such Contribution(s) was submitted. If You | ||
| institute patent litigation against any entity (including a | ||
| cross-claim or counterclaim in a lawsuit) alleging that the Work | ||
| or a Contribution incorporated within the Work constitutes direct | ||
| or contributory patent infringement, then any patent licenses | ||
| granted to You under this License for that Work shall terminate | ||
| as of the date such litigation is filed. | ||
|
|
||
| 4. Redistribution. You may reproduce and distribute copies of the | ||
| Work or Derivative Works thereof in any medium, with or without | ||
| modifications, and in Source or Object form, provided that You | ||
| meet the following conditions: | ||
|
|
||
| (a) You must give any other recipients of the Work or | ||
| Derivative Works a copy of this License; and | ||
|
|
||
| (b) You must cause any modified files to carry prominent notices | ||
| stating that You changed the files; and | ||
|
|
||
| (c) You must retain, in the Source form of any Derivative Works | ||
| that You distribute, all copyright, patent, trademark, and | ||
| attribution notices from the Source form of the Work, | ||
| excluding those notices that do not pertain to any part of | ||
| the Derivative Works; and | ||
|
|
||
| (d) If the Work includes a "NOTICE" text file as part of its | ||
| distribution, then any Derivative Works that You distribute must | ||
| include a readable copy of the attribution notices contained | ||
| within such NOTICE file, excluding those notices that do not | ||
| pertain to any part of the Derivative Works, in at least one | ||
| of the following places: within a NOTICE text file distributed | ||
| as part of the Derivative Works; within the Source form or | ||
| documentation, if provided along with the Derivative Works; or, | ||
| within a display generated by the Derivative Works, if and | ||
| wherever such third-party notices normally appear. The contents | ||
| of the NOTICE file are for informational purposes only and | ||
| do not modify the License. You may add Your own attribution | ||
| notices within Derivative Works that You distribute, alongside | ||
| or as an addendum to the NOTICE text from the Work, provided | ||
| that such additional attribution notices cannot be construed | ||
| as modifying the License. | ||
|
|
||
| You may add Your own copyright statement to Your modifications and | ||
| may provide additional or different license terms and conditions | ||
| for use, reproduction, or distribution of Your modifications, or | ||
| for any such Derivative Works as a whole, provided Your use, | ||
| reproduction, and distribution of the Work otherwise complies with | ||
| the conditions stated in this License. | ||
|
|
||
| 5. Submission of Contributions. Unless You explicitly state otherwise, | ||
| any Contribution intentionally submitted for inclusion in the Work | ||
| by You to the Licensor shall be under the terms and conditions of | ||
| this License, without any additional terms or conditions. | ||
| Notwithstanding the above, nothing herein shall supersede or modify | ||
| the terms of any separate license agreement you may have executed | ||
| with Licensor regarding such Contributions. | ||
|
|
||
| 6. Trademarks. This License does not grant permission to use the trade | ||
| names, trademarks, service marks, or product names of the Licensor, | ||
| except as required for reasonable and customary use in describing the | ||
| origin of the Work and reproducing the content of the NOTICE file. | ||
|
|
||
| 7. Disclaimer of Warranty. Unless required by applicable law or | ||
| agreed to in writing, Licensor provides the Work (and each | ||
| Contributor provides its Contributions) on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or | ||
| implied, including, without limitation, any warranties or conditions | ||
| of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A | ||
| PARTICULAR PURPOSE. You are solely responsible for determining the | ||
| appropriateness of using or redistributing the Work and assume any | ||
| risks associated with Your exercise of permissions under this License. | ||
|
|
||
| 8. Limitation of Liability. In no event and under no legal theory, | ||
| whether in tort (including negligence), contract, or otherwise, | ||
| unless required by applicable law (such as deliberate and grossly | ||
| negligent acts) or agreed to in writing, shall any Contributor be | ||
| liable to You for damages, including any direct, indirect, special, | ||
| incidental, or consequential damages of any character arising as a | ||
| result of this License or out of the use or inability to use the | ||
| Work (including but not limited to damages for loss of goodwill, | ||
| work stoppage, computer failure or malfunction, or any and all | ||
| other commercial damages or losses), even if such Contributor | ||
| has been advised of the possibility of such damages. | ||
|
|
||
| 9. Accepting Warranty or Additional Liability. While redistributing | ||
| the Work or Derivative Works thereof, You may choose to offer, | ||
| and charge a fee for, acceptance of support, warranty, indemnity, | ||
| or other liability obligations and/or rights consistent with this | ||
| License. However, in accepting such obligations, You may act only | ||
| on Your own behalf and on Your sole responsibility, not on behalf | ||
| of any other Contributor, and only if You agree to indemnify, | ||
| defend, and hold each Contributor harmless for any liability | ||
| incurred by, or claims asserted against, such Contributor by reason | ||
| of your accepting any such warranty or additional liability. | ||
|
|
||
| END OF TERMS AND CONDITIONS | ||
|
|
||
| APPENDIX: How to apply the Apache License to your work. | ||
|
|
||
| To apply the Apache License to your work, attach the following | ||
| boilerplate notice, with the fields enclosed by brackets "[]" | ||
| replaced with your own identifying information. (Don't include | ||
| the brackets!) The text should be enclosed in the appropriate | ||
| comment syntax for the file format. We also recommend that a | ||
| file or class name and description of purpose be included on the | ||
| same "printed page" as the copyright notice for easier | ||
| identification within third-party archives. | ||
|
|
||
| Copyright [yyyy] [name of copyright owner] | ||
|
|
||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
|
|
||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Tracked files relevant to licensing:"
git ls-files | rg '(^LICENSE$|^NOTICE$|docs/PRODUCTIZATION\.md$|README|LICENSE|notice|NOTICE|pom.xml|build.gradle|package.json|requirements.txt|Cargo.toml|pyproject.toml)' || true
echo
echo "LICENSE first/last 20 lines:"
sed -n '1,25p;190,201p' LICENSE 2>/dev/null || true
echo
echo "NOTICE contents:"
sed -n '1,80p' NOTICE 2>/dev/null || true
echo
echo "PRODUCTIZATION relevant excerpts:"
sed -n '200,240p' docs/PRODUCTIZATION.md 2>/dev/null || true
echo
echo "License/third-party detection in repo (sample terms):"
git ls-files -z | xargs -0 rg -n -i 'Apache License|Apache-2.0|licensed under|copyright|NOTICE|redistribution|third party|subdependencies|dependencies' --glob '!LICENSE' --glob '!NOTICE' --glob '!docs/**' -S | head -n 200Repository: Deathcharge/helix-cli
Length of output: 1928
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository location/check:"
pwd
git rev-parse --show-toplevel 2>&1 || true
git status --short 2>&1 || true
echo
echo "Tracked files relevant to licensing:"
git ls-files 2>&1 | rg '(^LICENSE$|^NOTICE$|(^|/)README|(^|/)NOTICE$|docs/PRODUCTIZATION\.md$|(^|/)(pom.xml|build.gradle|package.json|requirements.txt|pyproject.toml|Cargo.toml)$)' || true
echo
echo "LICENSE contents:"
if [ -f LICENSE ]; then wc -l LICENSE; sed -n '1,25p;185,201p' LICENSE; else echo "LICENSE missing"; fi
echo
echo "NOTICE contents:"
if [ -f NOTICE ]; then wc -l NOTICE; sed -n '1,80p' NOTICE; else echo "NOTICE missing"; fi
echo
echo "PRODUCTIZATION relevant excerpts:"
if [ -f docs/PRODUCTIZATION.md ]; then wc -l docs/PRODUCTIZATION.md; sed -n '200,240p' docs/PRODUCTIZATION.md; else echo "docs/PRODUCTIZATION.md missing"; fi
echo
echo "License/third-party references outside central license/notices/docs PRODUCTIZATION files:"
git ls-files -z 2>&1 | xargs -0 rg -n -i 'Apache License|Apache-2.0|licensed under|copyright|redistribution|third party|subdependencies|dependencies|NOTICE|LICENSE-|license' --glob '!LICENSE' --glob '!NOTICE' --glob '!docs/PRODUCTIZATION.md' -S | head -n 300 || trueRepository: Deathcharge/helix-cli
Length of output: 1928
Verify Apache-2.0 relicensing authority before publishing.
Align the Apache-2.0 license text with provenance, required attribution, and the release gate: complete the title/provenance review, ensure attribution/notice files accurately reflect all included third-party work, and make publication conditional on that audit.
📍 Affects 3 files
LICENSE#L1-L201(this comment)NOTICE#L1-L4docs/PRODUCTIZATION.md#L211-L212docs/PRODUCTIZATION.md#L229-L234
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@LICENSE` around lines 1 - 201, Verify the Apache-2.0 title and provenance
before publication, and make the release gate require completion of that audit.
In LICENSE, confirm the license text and attribution requirements; update NOTICE
at lines 1-4 to accurately cover all included third-party work; and update
docs/PRODUCTIZATION.md at lines 211-212 and 229-234 so publication is
conditional on the completed provenance and attribution review.
Comment on lines
+115
to
+137
| staging = Path( | ||
| tempfile.mkdtemp(prefix=f".{resolved_destination.name}.samsarix-", dir=parent) | ||
| ) | ||
| files = render_project(selected_name, module_name, template_name) | ||
| manifest_path = ".samsarix/project.json" | ||
| manifest = { | ||
| "files": sorted((*files, manifest_path)), | ||
| "generator": "samsarix-cli", | ||
| "generator_version": __version__, | ||
| "module_name": module_name, | ||
| "project_name": selected_name, | ||
| "schema_version": 1, | ||
| "template": template_name, | ||
| } | ||
| files[manifest_path] = json.dumps(manifest, indent=2, sort_keys=True) + "\n" | ||
|
|
||
| for relative_path, content in files.items(): | ||
| _write_file(staging, relative_path, content) | ||
|
|
||
| if initialize_git: | ||
| _initialize_git(staging) | ||
|
|
||
| os.replace(staging, resolved_destination) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Generated projects inherit mkdtemp's 0700 mode.
tempfile.mkdtemp creates the staging directory with mode 0700, and os.replace preserves it, so the delivered project directory is owner-only instead of umask-derived (0755 typically). This surprises users who serve, share, or COPY the generated tree.
🔧 Proposed fix: apply the process umask to the staging root
staging = Path(
tempfile.mkdtemp(prefix=f".{resolved_destination.name}.samsarix-", dir=parent)
)
+ current_umask = os.umask(0)
+ os.umask(current_umask)
+ staging.chmod(0o777 & ~current_umask)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| staging = Path( | |
| tempfile.mkdtemp(prefix=f".{resolved_destination.name}.samsarix-", dir=parent) | |
| ) | |
| files = render_project(selected_name, module_name, template_name) | |
| manifest_path = ".samsarix/project.json" | |
| manifest = { | |
| "files": sorted((*files, manifest_path)), | |
| "generator": "samsarix-cli", | |
| "generator_version": __version__, | |
| "module_name": module_name, | |
| "project_name": selected_name, | |
| "schema_version": 1, | |
| "template": template_name, | |
| } | |
| files[manifest_path] = json.dumps(manifest, indent=2, sort_keys=True) + "\n" | |
| for relative_path, content in files.items(): | |
| _write_file(staging, relative_path, content) | |
| if initialize_git: | |
| _initialize_git(staging) | |
| os.replace(staging, resolved_destination) | |
| staging = Path( | |
| tempfile.mkdtemp(prefix=f".{resolved_destination.name}.samsarix-", dir=parent) | |
| ) | |
| current_umask = os.umask(0) | |
| os.umask(current_umask) | |
| staging.chmod(0o777 & ~current_umask) | |
| files = render_project(selected_name, module_name, template_name) | |
| manifest_path = ".samsarix/project.json" | |
| manifest = { | |
| "files": sorted((*files, manifest_path)), | |
| "generator": "samsarix-cli", | |
| "generator_version": __version__, | |
| "module_name": module_name, | |
| "project_name": selected_name, | |
| "schema_version": 1, | |
| "template": template_name, | |
| } | |
| files[manifest_path] = json.dumps(manifest, indent=2, sort_keys=True) + "\n" | |
| for relative_path, content in files.items(): | |
| _write_file(staging, relative_path, content) | |
| if initialize_git: | |
| _initialize_git(staging) | |
| os.replace(staging, resolved_destination) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/scaffold.py` around lines 115 - 137, Adjust the
staging-directory setup in the scaffold flow around os.replace so the generated
project root receives the process umask-derived directory permissions instead of
retaining mkdtemp’s 0700 mode. Apply the umask to the staging root before
replacing it with resolved_destination, while leaving file generation and Git
initialization unchanged.
Comment on lines
+16
to
+41
| TEMPLATE_SPECS = ( | ||
| TemplateSpec( | ||
| name="fastapi", | ||
| summary="Small HTTP API with a health endpoint and Uvicorn runner.", | ||
| run_command="PROJECT_NAME", | ||
| ), | ||
| TemplateSpec( | ||
| name="flask", | ||
| summary="Small Flask service with a health endpoint.", | ||
| run_command="PROJECT_NAME", | ||
| ), | ||
| TemplateSpec( | ||
| name="streamlit", | ||
| summary="Interactive Streamlit application with one testable core function.", | ||
| run_command="python -m streamlit run src/MODULE_NAME/main.py", | ||
| ), | ||
| TemplateSpec( | ||
| name="discord", | ||
| summary="Discord bot with explicit token validation and minimal intents.", | ||
| run_command="PROJECT_NAME", | ||
| ), | ||
| ) | ||
|
|
||
| TEMPLATE_BY_NAME = {spec.name: spec for spec in TEMPLATE_SPECS} | ||
| TEMPLATE_NAMES = tuple(TEMPLATE_BY_NAME) | ||
| DEFAULT_TEMPLATE = "fastapi" |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Placeholder tokens in run_command leak into the templates --json contract.
templates --json emits "run_command": "PROJECT_NAME" verbatim with no documented substitution rule. Use an obviously templated form (e.g. <project-name> / src/<module_name>/main.py) or document the tokens in the JSON contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/templates.py` around lines 16 - 41, Update the run_command
values in TEMPLATE_SPECS to use clearly templated placeholder forms, including
the project command and Streamlit module path, so templates --json does not
expose undocumented raw tokens. Keep the existing command semantics and template
names unchanged.
Comment on lines
+52
to
+54
| "[build-system]", | ||
| 'requires = ["setuptools>=83,<84", "wheel>=0.45,<1"]', | ||
| 'build-backend = "setuptools.build_meta"', |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Single-minor build backend pin will need churn every setuptools release.
setuptools 83.0.0 is the current release (published Jul 4, 2026), so >=83,<84 resolves today, but every generated project is locked to one minor line and the template must be edited on each bump. A floor plus major-cap (e.g. setuptools>=77,<84) keeps PEP 621 support without the maintenance treadmill. Note README line 141 hardcodes the same pin and must stay in sync.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/templates.py` around lines 52 - 54, Broaden the setuptools
requirement in the build-system template from the single-minor range to a
supported floor with the existing major-version cap, and update the matching
hardcoded requirement in the README so both remain synchronized.
Comment on lines
+108
to
+180
| return ( | ||
| dedent( | ||
| f""" | ||
| # {project_name} | ||
|
|
||
| A standalone Python project generated with the Samsarix CLI `{template_name}` template. | ||
| It has no runtime dependency on Samsarix CLI or on a hosted service. | ||
|
|
||
| ## Requirements | ||
|
|
||
| - Python 3.11 or newer | ||
|
|
||
| ## Setup | ||
|
|
||
| ```bash | ||
| python -m venv .venv | ||
| ``` | ||
|
|
||
| Activate the environment: | ||
|
|
||
| ```powershell | ||
| # Windows PowerShell | ||
| .venv\\Scripts\\Activate.ps1 | ||
| ``` | ||
|
|
||
| ```bash | ||
| # macOS or Linux | ||
| source .venv/bin/activate | ||
| ``` | ||
|
|
||
| Install the application and development tools: | ||
|
|
||
| ```bash | ||
| python -m pip install --upgrade pip "setuptools>=83,<84" | ||
| python -m pip install -e ".[dev]" | ||
| ``` | ||
|
|
||
| ## Run | ||
|
|
||
| ```bash | ||
| {run_command} | ||
| ``` | ||
|
|
||
| {configuration} | ||
|
|
||
| ## Verify | ||
|
|
||
| ```bash | ||
| pytest | ||
| ruff check . | ||
| ruff format --check . | ||
| ``` | ||
|
|
||
| If Samsarix CLI is installed, its structural check is also available: | ||
|
|
||
| ```bash | ||
| samsarix check . | ||
| ``` | ||
|
|
||
| ## Layout | ||
|
|
||
| - `src/{module_name}/`: application source | ||
| - `tests/`: focused tests | ||
| - `.samsarix/project.json`: generator metadata used by `samsarix check` | ||
|
|
||
| ## License | ||
|
|
||
| No license is selected for generated projects. Choose and add a license before | ||
| redistributing this project. | ||
| """ | ||
| ).strip() | ||
| + "\n" | ||
| ) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
dedent after interpolation silently breaks the generated discord README.
dedent runs on the already-interpolated string, so the multi-line, left-aligned configuration block passed by _discord_files (lines 415-434) makes the common leading whitespace empty and dedent a no-op. Every line of the discord README then keeps its 12-space indent, turning headings and prose into Markdown code blocks. tests/test_scaffold.py line 35 misses this because it only greps for a substring.
Dedent first, substitute after (and consider asserting README.md starts with "# " in the parametrized template test):
🐛 Proposed fix: substitute the configuration after dedenting
- return (
- dedent(
- f"""
+ body = dedent(
+ f"""
# {project_name}
@@
- {configuration}
+ __SAMSARIX_CONFIGURATION__
@@
- """
- ).strip()
- + "\n"
- )
+ """
+ ).strip()
+ return body.replace("__SAMSARIX_CONFIGURATION__", configuration) + "\n"(The intervening README body lines stay unchanged.)
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| return ( | |
| dedent( | |
| f""" | |
| # {project_name} | |
| A standalone Python project generated with the Samsarix CLI `{template_name}` template. | |
| It has no runtime dependency on Samsarix CLI or on a hosted service. | |
| ## Requirements | |
| - Python 3.11 or newer | |
| ## Setup | |
| ```bash | |
| python -m venv .venv | |
| ``` | |
| Activate the environment: | |
| ```powershell | |
| # Windows PowerShell | |
| .venv\\Scripts\\Activate.ps1 | |
| ``` | |
| ```bash | |
| # macOS or Linux | |
| source .venv/bin/activate | |
| ``` | |
| Install the application and development tools: | |
| ```bash | |
| python -m pip install --upgrade pip "setuptools>=83,<84" | |
| python -m pip install -e ".[dev]" | |
| ``` | |
| ## Run | |
| ```bash | |
| {run_command} | |
| ``` | |
| {configuration} | |
| ## Verify | |
| ```bash | |
| pytest | |
| ruff check . | |
| ruff format --check . | |
| ``` | |
| If Samsarix CLI is installed, its structural check is also available: | |
| ```bash | |
| samsarix check . | |
| ``` | |
| ## Layout | |
| - `src/{module_name}/`: application source | |
| - `tests/`: focused tests | |
| - `.samsarix/project.json`: generator metadata used by `samsarix check` | |
| ## License | |
| No license is selected for generated projects. Choose and add a license before | |
| redistributing this project. | |
| """ | |
| ).strip() | |
| + "\n" | |
| ) | |
| body = dedent( | |
| f""" | |
| # {project_name} | |
| A standalone Python project generated with the Samsarix CLI `{template_name}` template. | |
| It has no runtime dependency on Samsarix CLI or on a hosted service. | |
| ## Requirements | |
| - Python 3.11 or newer | |
| ## Setup |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/templates.py` around lines 108 - 180, Update the README template
construction in the visible template-rendering function so dedent is applied
before interpolating the multi-line configuration value, preserving normal
Markdown indentation for Discord-generated README files. Keep the existing
README body and substitutions unchanged, and strengthen the parametrized
scaffold test to assert generated README.md begins with “# ”.
Comment on lines
+30
to
+40
| def _read_bounded(path: Path, limit: int, label: str) -> bytes: | ||
| try: | ||
| size = path.stat().st_size | ||
| except OSError as exc: | ||
| raise ValueError(f"cannot read {label}: {exc}") from exc | ||
| if size > limit: | ||
| raise ValueError(f"{label} exceeds the {limit}-byte safety limit") | ||
| try: | ||
| return path.read_bytes() | ||
| except OSError as exc: | ||
| raise ValueError(f"cannot read {label}: {exc}") from exc |
There was a problem hiding this comment.
🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win
Enforce the byte cap during the read, not via a prior stat.
The size check and the read are separate syscalls, so a file that grows in between is read in full — the cap is advisory rather than enforced. Reading limit + 1 bytes makes the bound authoritative and drops one syscall.
♻️ Proposed refactor
def _read_bounded(path: Path, limit: int, label: str) -> bytes:
try:
- size = path.stat().st_size
+ with path.open("rb") as handle:
+ payload = handle.read(limit + 1)
except OSError as exc:
raise ValueError(f"cannot read {label}: {exc}") from exc
- if size > limit:
+ if len(payload) > limit:
raise ValueError(f"{label} exceeds the {limit}-byte safety limit")
- try:
- return path.read_bytes()
- except OSError as exc:
- raise ValueError(f"cannot read {label}: {exc}") from exc
+ return payload📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| def _read_bounded(path: Path, limit: int, label: str) -> bytes: | |
| try: | |
| size = path.stat().st_size | |
| except OSError as exc: | |
| raise ValueError(f"cannot read {label}: {exc}") from exc | |
| if size > limit: | |
| raise ValueError(f"{label} exceeds the {limit}-byte safety limit") | |
| try: | |
| return path.read_bytes() | |
| except OSError as exc: | |
| raise ValueError(f"cannot read {label}: {exc}") from exc | |
| def _read_bounded(path: Path, limit: int, label: str) -> bytes: | |
| try: | |
| with path.open("rb") as handle: | |
| payload = handle.read(limit + 1) | |
| except OSError as exc: | |
| raise ValueError(f"cannot read {label}: {exc}") from exc | |
| if len(payload) > limit: | |
| raise ValueError(f"{label} exceeds the {limit}-byte safety limit") | |
| return payload |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/validation.py` around lines 30 - 40, Update _read_bounded to
enforce the byte cap during reading: remove the preliminary path.stat size check
and read at most limit + 1 bytes, then raise the existing safety-limit
ValueError when more than limit bytes are returned. Preserve the existing
OSError-to-ValueError handling and labels.
Comment on lines
+94
to
+95
| if len(values) != len(set(value for value in values if isinstance(value, str))): | ||
| issues.append("manifest files contains duplicate paths") |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Duplicate detection misfires when files holds non-string entries.
len(values) is compared against a set built only from string entries, so ["README.md", 7] reports a bogus "duplicate paths" issue on top of the correct unsafe-path issue. Compare like with like.
🐛 Proposed fix
- if len(values) != len(set(value for value in values if isinstance(value, str))):
+ string_values = [value for value in values if isinstance(value, str)]
+ if len(string_values) != len(set(string_values)):
issues.append("manifest files contains duplicate paths")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| if len(values) != len(set(value for value in values if isinstance(value, str))): | |
| issues.append("manifest files contains duplicate paths") | |
| string_values = [value for value in values if isinstance(value, str)] | |
| if len(string_values) != len(set(string_values)): | |
| issues.append("manifest files contains duplicate paths") |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/validation.py` around lines 94 - 95, Update the duplicate-path
check in the manifest validation logic to compare only string entries on both
sides, so non-string values are excluded from the duplicate count while still
being handled by the existing unsafe-path validation. Preserve duplicate
detection for repeated string paths.
Comment on lines
+155
to
+156
| if project_table.get("requires-python") != ">=3.11": | ||
| issues.append("pyproject.toml project.requires-python must be '>=3.11'") |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win
Exact requires-python equality punishes legitimate downstream changes.
A generated project that raises its floor to >=3.12 (a normal owner decision for an independent project) now fails samsarix check. Validate that the declared specifier still requires 3.11 or newer instead of string-matching the generator's original value.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@samsarix_cli/validation.py` around lines 155 - 156, Update the
requires-python validation in the project-table check to parse the declared
specifier and accept configurations whose minimum supported Python version is
3.11 or newer, including values such as >=3.12, rather than requiring exact
equality with ">=3.11". Preserve reporting an issue for missing, invalid, or
lower minimum-version declarations.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merge intent
This PR integrates the reviewed productization branch and its repository-specific roadmap. Merge is distinct from release, publication, deployment, or adoption as a canonical Samsarix Unified subsystem.
Portfolio contract
Verification
The portfolio merge-readiness pass compared this branch with its default, inspected its flagship relationship, and found no merge-blocking regression. Repository CI and any additional local verification remain recorded in the portfolio audit ledger.