Skip to content

docs(skill): follow magic_starter off the alpha rail - #155

Open
anilcancakir wants to merge 2 commits into
masterfrom
docs/starter-0-0-27-reference
Open

docs(skill): follow magic_starter off the alpha rail#155
anilcancakir wants to merge 2 commits into
masterfrom
docs/starter-0-0-27-reference

Conversation

@anilcancakir

@anilcancakir anilcancakir commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

magic_starter leaves the alpha rail at its next release (fluttersdk/magic_starter#129): 0.0.1-alpha.26 is followed by 0.0.27, carrying the counter rather than resetting it. This is the sibling half of that change.

skills/magic-framework/references/plugin-starter.md is the only agent-facing document that package has, since .pubignore keeps its CLAUDE.md and .claude/ out of the published archive, and it is versioned by THIS repo's releases rather than by that package's. magic_starter/test/skill_reference_stamp_test.dart fails against a stale stamp whenever a sibling checkout exists, so this file has to move in step.

What changed

  • Stamp v0.0.1-alpha.27 to v0.0.27, and the (alpha.27) release marker on the intended-url paragraph reads (0.0.27). The older markers (alpha.19, alpha.22, alpha.23, alpha.25) are left alone: those releases really were named that, and the file uses them as history.
  • The stated magic_notifications requirement moves from ^0.2.0 to ^0.3.0, which is the floor the starter release carries.
  • A sentence on the rail change itself, because an agent reading pub.dev sees 0.0.27 arrive after 0.0.1-alpha.26 and needs to know an existing ^0.0.1-alpha.N pin already covers it (a caret on a zero major ends at 0.1.0).
  • The notification section gains the five notifications.* keys the mounted screens read and no package supplies: bulk_title, bulk_description, delete, delete_failed, channel_sms. starter:install scaffolds them; an upgrade with a hand-written catalogue renders each key as its own text until they are added by hand.
  • SKILL.md version 0.1.16 to 0.1.17, per the rule that it moves when reference content moves.

Markdown only, no source or test touched.

Author: Anılcan Çakır anilcan.cakir@gmail.com

magic_starter's next release is 0.0.27 rather than 0.0.1-alpha.27, so the
reference stamp moves with it and the release markers inside the file read
0.0.27 where they described that release. Its magic_notifications requirement
moves to ^0.3.0, the floor the starter release carries.

The notification section gains the five notifications.* keys the mounted
screens read and no package supplies: bulk_title, bulk_description, delete,
delete_failed and channel_sms. An adopter upgrading with a hand-written
catalogue sees each rendered as its own key, and this file is the only
agent-facing document for that package because .pubignore keeps its CLAUDE.md
out of the published archive.

SKILL.md's version moves to 0.1.17 because reference content moved.
@codecov

codecov Bot commented Sep 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@kodizm

kodizm Bot commented Sep 11, 2026

Copy link
Copy Markdown

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

Markdown-only stamp and content update that checks out: the pub-resolution claim, the translation keys, and the changelog placement are all accurate; one small internal inconsistency left over.

Minor

skills/magic-framework/references/plugin-starter.md:654 — maintainability. The "raw key rendering" troubleshooting row still ends its upgrade history at alpha.26 (common.delete, notifications.delete_confirm_title, notifications.delete_confirm_message). The five keys this PR documents for 0.0.27 are only in the notification section at line 228, so an agent that lands in the troubleshooting table diagnosing exactly this symptom gets a list that no longer covers the newest release.

Notes (not blocking)

  • The caret claim on line 7 is correct, and it is the sort of thing that is easy to get wrong (npm's ^0.0.x would not cover it). Verified against real pub resolution: magic: ^0.0.1-alpha.26 resolves to 0.0.10, so the upper bound is 0.1.0 and a ^0.0.1-alpha.N pin does pick up 0.0.27.
  • Line 228's keys check out against the published magic_notifications 0.2.0 source: trans('notifications.delete') is the semanticLabel in notifications_list_view.dart:366, with delete_failed at :387 and channel_sms in notification_preferences_view.dart:386; none appear in magic_starter alpha.26's en.stub, so "no package supplies" holds. bulk_title/bulk_description are attributed to the unreleased 0.3.0 and could not be verified.
  • Both magic_starter 0.0.27 and magic_notifications 0.3.0 are unpublished at review time (pub.dev latest: 0.0.1-alpha.26 and 0.2.0), so this doc leads its packages. That matches the stated sibling-release arrangement and the existing plugin-notifications.md stamp of v0.3.0, so I am reading it as intentional rather than a finding.

Tests

No test covers the reference text, and this repo has no stamp assertion for it (grep over test/ for SKILL.md/plugin-starter returns nothing); the test named in the description lives in magic_starter. Nothing to add here for a markdown-only change.

Checks I ran

  • read_pull_request_diff (manifest + all 3 patches, scope: full) - all changed files read, none dropped.
  • dart pub get on a scratch pubspec with magic: ^0.0.1 and magic: ^0.0.1-alpha.26 - both resolved magic 0.0.10, exit 0, confirming the 0.1.0 upper bound.
  • curl [external link removed] - latest 0.0.1-alpha.26and0.2.0`.
  • grep over the published magic_starter-0.0.1-alpha.26 and magic_notifications-0.2.0 sources for the five notifications.* keys.
  • No linter, analyzer or test run: no Dart source changed.

Three commits landed on that package's main after the stamp move was written
(#130, #131, #132), all into the same unreleased section, so the release this
file is stamped for now ships more than it described.

The configuration block gains notifications.external_id_prefix and a paragraph
on the identity lifecycle: the provider declares <prefix><user id> off
Auth.stateNotifier, releases it when a session ends, and reads the current
state once at boot. The value has to equal the backend's own, since OneSignal
accepts a mismatch and delivers to nobody, so the only trace is a
zero-recipient report on the server. starter:doctor reports the resolved
prefix and never fails on it, because three of the four sites that compose the
id live in magic-starter-laravel.

Also records that polling now stops on the two sign-outs the auth controller
never sees, which is the one behaviour an app could notice.
@kodizm

kodizm Bot commented Sep 11, 2026

Copy link
Copy Markdown

Note

Kodizm (AI-generated). May contain mistakes; verify before acting.

Incremental re-review of 65e0342 only: the new notifications.external_id_prefix section documents real magic-side APIs correctly and the CHANGELOG entry moved with it, so nothing new to flag.

Tests

Still markdown-only, still nothing in this repo asserting the reference text (the stamp test lives in magic_starter). Nothing to add.

Checks I ran

  • read_pull_request_diff with since_sha=6900f62, scope: incremental - 2 files (CHANGELOG.md, plugin-starter.md), both patches read, none dropped.
  • grep lib/src for the magic APIs the new paragraph names: Auth.stateNotifier exists (lib/src/facades/auth.dart:194, backed by base_guard.dart:54), and the "AuthInterceptor failing a token refresh" sign-out is real: lib/src/auth/auth_interceptor.dart:76-77 logs Auth: Token refresh failed, logging out then calls Auth.logout().
  • pub.dev API: magic_starter latest is still 0.0.1-alpha.26 and magic_notifications still 0.2.0, so the provider-side behaviour claimed for 0.0.27 (external-id declare/release, starter:doctor printing the prefix, the blank-value fallback to user_) is unpublished and could not be verified from source; as before I read the doc leading its package as the intended sibling-release arrangement.
  • No analyzer, formatter or test run: no Dart source changed.

My earlier minor note on the troubleshooting row (plugin-starter.md:669 still ending its raw-key upgrade history at alpha.26) is untouched by these commits and stands as written; this commit adds config keys rather than translation keys, so it does not widen it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant